1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \title Widget Appearance and Style
31 \brief Classes used for customizing UI appearance and style.
35 \page style-reference.html
36 \title Styles and Style Aware Widgets
37 \ingroup qt-gui-concepts
38 \brief Styles and the styling of widgets.
40 Styles (classes that inherit QStyle) draw on behalf of widgets
41 and encapsulate the look and feel of a GUI. The QStyle class is
42 an abstract base class that encapsulates the look and feel of a
43 GUI. Qt's built-in widgets use it to perform nearly all of their
44 drawing, ensuring that they look exactly like the equivalent
47 Several styles are built into Qt (e.g., windows style and motif style).
48 Other styles are only available on specific platforms (such as
49 the windows XP style). Custom styles are made available as plugins
50 or by creating an instance of the style class in an application and
51 setting it with QApplication::setStyle().
53 To implement a new style, you inherit one of Qt's existing styles
54 - the one most resembling the style you want to create - and
55 reimplement a few virtual functions. This process is somewhat
56 involved, and we therefore provide this overview. We give a
57 step-by-step walkthrough of how to style individual Qt widgets.
58 We will examine the QStyle virtual functions, member variables,
61 The part of this document that does not concern the styling of
62 individual widgets is meant to be read sequentially because later
63 sections tend to depend on earlier ones. The description of the
64 widgets can be used for reference while implementing a style.
65 However, you may need to consult the Qt source code in some cases.
66 The sequence in the styling process should become clear after
67 reading this document, which will aid you in locating relevant code.
69 To develop style aware widgets (i.e., widgets that conform to
70 the style in which they are drawn), you need to draw them using the
71 current style. This document shows how widgets draw themselves
72 and which possibilities the style gives them.
74 \section1 Classes for Widget Styling
76 These classes are used to customize an application's appearance and
79 \annotatedlist appearance
81 \section1 The QStyle implementation
83 The API of QStyle contains functions that draw the widgets, static
84 helper functions to do common and difficult tasks (e.g.,
85 calculating the position of slider handles) and functions to do
86 the various calculations necessary while drawing (e.g., for the
87 widgets to calculate their size hints). The style also help some
88 widgets with the layout of their contents. In addition, it creates
89 a QPalette that contains \l{QBrush}es to draw with.
91 QStyle draws graphical elements; an element is a widget or a
92 widget part like a push button bevel, a window frame, or a scroll
93 bar. Most draw functions now take four arguments:
96 \o an enum value specifying which graphical element to draw
97 \o a QStyleOption specifying how and where to render that element
98 \o a QPainter that should be used to draw the element
99 \o a QWidget on which the drawing is performed (optional)
102 When a widget asks a style to draw an element, it provides the style
103 with a QStyleOption, which is a class that contains the information
104 necessary for drawing. Thanks to QStyleOption, it is possible to make
105 QStyle draw widgets without linking in any code for the widget. This
106 makes it possible to use \l{QStyle}'s draw functions on any paint
107 device, i.e., you can draw a combobox on any widget, not just on a
110 The widget is passed as the last argument in case the style needs
111 it to perform special effects (such as animated default buttons on
112 Mac OS X), but it isn't mandatory.
114 We will in the course of this section look at the style elements,
115 the style options, and the functions of QStyle. Finally, we describe
116 how the palette is used.
118 Items in item views is drawn by \l{Delegate Classes}{delegates} in
119 Qt. The item view headers are still drawn by the style. Qt's
120 default delegate, QStyledItemDelegate, draws its items partially
121 through the current style; it draws the check box indicators and
122 calculate bounding rectangles for the elements of which the item
123 consists. In this document, we only describe how to implement a
124 QStyle subclass. If you wish to add support for other datatypes
125 than those supported by the QStyledItemDelegate, you need to
126 implement a custom delegate. Note that delegates must be set
127 programmatically for each individual widget (i.e., default
128 delegates cannot be provided as plugins).
130 \section2 The Style Elements
132 A style element is a graphical part of a GUI. A widget consists
133 of a hierarchy (or tree) of style elements. For instance, when a
134 style receives a request to draw a push button (from QPushButton,
135 for example), it draws a label (text and icon), a button bevel,
136 and a focus frame. The button bevel, in turn, consists of a frame
137 around the bevel and two other elements, which we will look at
138 later. Below is a conceptual illustration of the push button
139 element tree. We will see the actual tree for QPushButton when we
140 go through the individual widgets.
142 \image javastyle/conceptualpushbuttontree.png
144 Widgets are not necessarily drawn by asking the style to draw
145 only one element. Widgets can make several calls to the style to
146 draw different elements. An example is QTabWidget, which draws its
147 tabs and frame individually.
149 There are three element types: primitive elements, control
150 elements, and complex control elements. The elements are defined
151 by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement},
152 and \l{QStyle::}{PrimitiveElement} enums. The values of
153 each element enum has a prefix to identify their type: \c{CC_} for
154 complex elements, \c{CE_} for control elements, and \c{PE_} for
155 primitive elements. We will in the following three sections see what
156 defines the different elements and see examples of widgets that use
159 The QStyle class description contains a list of these elements and
160 their roles in styling widgets. We will see how they are used when
161 we style individual widgets.
163 \section3 Primitive Elements
165 Primitive elements are GUI elements that are common and often used
166 by several widgets. Examples of these are frames, button bevels,
167 and arrows for spin boxes, scroll bars, and combo boxes.
168 Primitive elements cannot exist on their own: they are always part
169 of a larger construct. They take no part in the interaction with
170 the user, but are passive decorations in the GUI.
172 \section3 Control Elements
174 A control element performs an action or displays information
175 to the user. Examples of control elements are push buttons, check
176 boxes, and header sections in tables and tree views. Control
177 elements are not necessarily complete widgets such as push
178 buttons, but can also be widget parts such as tab bar tabs and
179 scroll bar sliders. They differ from primitive elements in that
180 they are not passive, but fill a function in the interaction with
181 the user. Controls that consist of several elements often use the
182 style to calculate the bounding rectangles of the elements. The
183 available sub elements are defined by the \l{QStyle::}{SubElement}
184 enum. This enum is only used for calculating bounding rectangles,
185 and sub elements are as such not graphical elements to be drawn
186 like primitive, control, and complex elements.
188 \section3 Complex Control Elements
190 Complex control elements contain sub controls. Complex controls
191 behave differently depending on where the user handles them with
192 the mouse and which keyboard keys are pressed. This is dependent
193 on which sub control (if any) that the mouse is over or received a
194 mouse press. Examples of complex controls are scroll bars and
195 combo boxes. With a scroll bar, you can use the mouse to move the
196 slider and press the line up and line down buttons. The available
197 sub controls are defined by the \l{QStyle}{SubControl} enum.
199 In addition to drawing, the style needs to provide the widgets
200 with information on which sub control (if any) a mouse press was
201 made on. For instance, a QScrollBar needs to know if the user
202 pressed the slider, the slider groove, or one of the buttons.
204 Note that sub controls are not the same as the control elements
205 described in the previous section. You cannot use the style to
206 draw a sub control; the style will only calculate the bounding
207 rectangle in which the sub control should be drawn. It is common,
208 though, that complex elements use control and primitive elements
209 to draw their sub controls, which is an approach that is
210 frequently used by the built-in styles in Qt and also the Java
211 style. For instance, the Java style uses PE_IndicatorCheckBox to
212 draw the check box in group boxes (which is a sub control of
213 CC_GroupBox). Some sub controls have an equivalent control element,
214 e.g., the scroll bar slider (SC_SCrollBarSlider and
217 \section3 Other QStyle Tasks
219 The style elements and widgets, as mentioned, use the style to
220 calculate bounding rectangles of sub elements and sub controls,
221 and pixel metrics, which is a style dependent size in screen
222 pixels, for measures when drawing. The available rectangles and
223 pixel metrics are represented by three enums in QStyle:
224 \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and
225 \l{QStyle::}{PixelMetric}. Values of the enums can easily by
226 identified as they start with SE_, SC_ and PM_.
228 The style also contain a set of style hints, which is
229 represented as values in the \l{QStyle::}{StyleHint} enum. All
230 widgets do not have the same functionality and look in the
231 different styles. For instance, when the menu items in a menu do not
232 fit in a single column on the screen, some styles support
233 scrolling while others draw more than one column to fit all items.
235 A style usually has a set of standard images (such as a warning, a
236 question, and an error image) for message boxes, file dialogs,
237 etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its
238 values represent the standard images. Qt's widgets use these, so
239 when you implement a custom style you should supply the images
240 used by the style that is being implemented.
242 The style calculates the spacing between widgets in layouts. There
243 are two ways the style can handle these calculations. You can set
244 the PM_LayoutHorizontalSpacing and PM_LayoutVerticalSpacing, which
245 is the way the java style does it (through QCommonStyle).
246 Alternatively, you can implement QStyle::layoutSpacing() and
247 QStyle::layoutSpacingImplementation() if you need more control over
248 this part of the layout. In these functions you can calculate the
249 spacing based on control types (QSizePolicy::ControlType) for
250 different size policies (QSizePolicy::Policy) and also the style
251 option for the widget in question.
253 \section2 Style Options
255 The sub-classes of QStyleOption contain all information necessary
256 to style the individual elements. Style options are instantiated -
257 usually on the stack - and filled out by the caller of the QStyle
258 function. Depending on what is drawn the style will expect
259 different a different style option class. For example, the
260 QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect
261 argument, and it's possible to create custom subclasses that a
262 custom style can use. The style options keep public variables
263 for performance reasons.
265 The widgets can be in a number of different states, which are
266 defined by the \l{QStyle::}{State} enum. Some of the state flags have
267 different meanings depending on the widget, but others are common
268 for all widgets like State_Disabled. It is QStyleOption that sets
269 the common states with QStyleOption::initFrom(); the rest of the
270 states are set by the individual widgets.
272 Most notably, the style options contain the palette and bounding
273 rectangles of the widgets to be drawn. Most widgets have
274 specialized style options. QPushButton and QCheckBox, for
275 instance, use QStyleOptionButton as style option, which contain
276 the text, icon, and the size of their icon. The exact contents of
277 all options are described when we go through individual widgets.
279 When reimplementing QStyle functions that take a
280 QStyleOption parameter, you often need to cast the
281 QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
282 safety, you can use qstyleoption_cast() to ensure that the
283 pointer type is correct. If the object isn't of the right type,
284 qstyleoption_cast() returns 0. For example:
286 \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0
288 The following code snippet illustrates how to use QStyle to
289 draw the focus rectangle from a custom widget's paintEvent():
291 \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1
293 The next example shows how to derive from an existing style to
294 customize the look of a graphical element:
296 \snippet doc/src/snippets/customstyle/customstyle.h 0
298 \snippet doc/src/snippets/customstyle/customstyle.cpp 2
299 \snippet doc/src/snippets/customstyle/customstyle.cpp 3
300 \snippet doc/src/snippets/customstyle/customstyle.cpp 4
302 \section2 QStyle Functions
304 The QStyle class defines three functions for drawing the primitive,
305 control, and complex elements:
306 \l{QStyle::}{drawPrimitive()},
307 \l{QStyle::}{drawControl()}, and
308 \l{QStyle::}{drawComplexControl()}. The functions takes the
309 following parameters:
312 \o the enum value of the element to draw
313 \o a QStyleOption which contains the information needed to
315 \o a QPainter with which to draw the element.
316 \o a pointer to a QWidget, typically the widget
317 that the element is painted on.
320 Not all widgets send a pointer to themselves. If the style
321 option sent to the function does not contain the information you
322 need, you should check the widget implementation to see if it
323 sends a pointer to itself.
325 The QStyle class also provides helper functions that are used
326 when drawing the elements. The \l{QStyle::}{drawItemText()}
327 function draws text within a specified rectangle and taking a
328 QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()}
329 function helps to align a pixmap within a specified bounding
332 Other QStyle functions do various calculations for the
333 functions that draw. The widgets also use these functions for
334 calculating size hints and also for bounding rectangle
335 calculations if they draw several style elements themselves.
336 As with the functions that draw elements the helper functions
337 typically takes the same arguments.
340 \o The \l{QStyle::}{subElementRect()} function takes a
341 \l{QStyle::}{SubElement} enum value, and calculates a bounding
342 rectangle for a sub element. The style uses this function to
343 know where to draw the different parts of an element. This is
344 mainly done for reuse. If you create a new style, you can use
345 the same location of sub elements as the super class.
347 \o The \l{QStyle::}{subControlRect()} function is used to
348 calculate bounding rectangles for sub controls in complex
349 controls. When you implement a new style, you reimplement \c
350 subControlRect() and calculate the rectangles that are different
351 from the super class.
353 \o The \l{QStyle::}{pixelMetric()} function returns a pixel
354 metric, which is a style dependent size given in screen
355 pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum
356 and returns the correct measure. Note that pixel metrics do
357 not necessarily have to be static measures, but can be
358 calculated with, for example, the style option.
360 \o The \l{QStyle::}{hitTestComplexControl()} function returns the
361 sub control that the mouse pointer is over in a complex control.
362 Usually, this is simply a matter of using
363 \l{QStyle::}{subControlRect()} to get the bounding rectangles of
364 the sub controls, and see which rectangle contains the position of
368 QStyle also have the functions \l{QStyle::}{polish()} and
369 \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish()
370 function before being shown and to \c unpolish() when they
371 are hidden. You can use these functions to set attributes on the
372 widgets or do other work that is required by your style. For
373 instance, if you need to know when the mouse is hovering over the
374 widget, you need to set the \l{Qt::}{WA_Hover} widget attribute.
375 The State_MouseOver state flag will then be set in the widget's
378 QStyle has a few static helper functions that do some common and
379 difficult tasks. They can calculate the position of a slider
380 handle from the value of the slider and transform rectangles
381 and draw text considering reverse layouts; see the QStyle
382 class documentation for more details.
384 The usual approach when one reimplements QStyle virtual
385 functions is to do work on elements that are different from the
386 super class; for all other elements, you can simply use the super
387 class implementation.
389 \section2 The Palette
391 Each style provides a color - that is, QBrush - palette that
392 should be used for drawing the widgets. There is one set of colors
393 for the different widget states (QPalette::ColorGroup): active
394 (widgets in the window that has keyboard focus), inactive (widgets
395 used for other windows), and disabled (widgets that are set
396 disabled). The states can be found by querying the State_Active
397 and State_Enabled state flags. Each set contains color certain
398 roles given by the QPalette::ColorRole enum. The roles describe in
399 which situations the colors should be used (e.g., for painting
400 widget backgrounds, text, or buttons).
402 How the color roles are used is up to the style. For instance, if
403 the style uses gradients, one can use a palette color and make it
404 darker or lighter with QColor::darker() and QColor::lighter() to
405 create the gradient. In general, if you need a brush that is not
406 provided by the palette, you should try to derive it from one.
408 QPalette, which provides the palette, stores colors for
409 different widget states and color roles. The palette for a style
410 is returned by \l{QStyle::}{standardPalette()}. The standard
411 palette is not installed automatically when a new style is set
412 on the application (QApplication::setStyle()) or widget
413 (QWidget::setStyle()), so you must set the palette yourself
414 with (QApplication::setPalette()) or (QWidget::setPalette()).
416 It is not recommended to hard code colors as applications and
417 individual widgets can set their own palette and also use the
418 styles palette for drawing. Note that none of Qt's widgets set
419 their own palette. The java style does hard code some colors, but
420 its author looks past this in silence. Of course, it is not
421 intended that the style should look good with any palette.
423 \section2 Implementation Issues
425 When you implement styles, there are several issues to
426 consider. We will give some hints and advice on implementation
429 When implementing styles, it is necessary to look through the
430 code of the widgets and code of the base class and its ancestors.
431 This is because the widgets use the style differently, because the
432 implementation in the different styles virtual functions can
433 affect the state of the drawing (e.g., by altering the QPainter
434 state without restoring it and drawing some elements without using
435 the appropriate pixel metrics and sub elements).
437 It is recommended that the styles do not alter the proposed size
438 of widgets with the QStyle::sizeFromContents() function but let
439 the QCommonStyle implementation handle it. If changes need to be
440 made, you should try to keep them small; application development
441 may be difficult if the layout of widgets looks considerably
442 different in the various styles.
444 We recommend using the QPainter directly for drawing, i.e., not
445 use pixmaps or images. This makes it easier for the style conform
446 to the palette (although you can set your own color table on a
447 QImage with \l{QImage::}{setColorTable()}).
449 It is, naturally, possible to draw elements without using the
450 style to draw the sub elements as intended by Qt. This is
451 discouraged as custom widgets may depend on these sub elements to
452 be implemented correctly. The widget walkthrough shows how Qt
453 uses the sub elements.
457 We have implemented a style that resembles the Java default look
458 and feel (previously known as Metal). We have done this as it is
459 relatively simple to implement and we wanted to build a style for
460 this overview document. To keep it simple and not to extensive, we
461 have simplified the style somewhat, but Qt is perfectly able to
462 make an exact copy of the style. However, there are no concrete
463 plans to implement the style as a part of Qt.
465 In this section we will have a look at some implementation
466 issues. Finally, we will see a complete example on the styling of
467 a Java widget. We will continue to use the java style
468 throughout the document for examples and widget images. The
469 implementation itself is somewhat involved, and it is not
470 intended that you should read through it.
472 \section2 Design and Implementation
474 The first step in designing the style was to select the base
475 class. We chose to subclass QWindowsStyle. This class implements
476 most of the functionality we need other than performing the actual
477 drawing. Also, windows and java share layout of sub controls for
478 several of the complex controls (which reduces the amount of code
479 required considerably).
481 The style is implemented in one class. We have done this
482 because we find it convenient to keep all code in one file. Also,
483 it is an advantage with regards to optimization as we instantiate
484 less objects. We also keep the number of functions at a minimum by
485 using switches to identify which element to draw in the functions.
486 This results in large functions, but since we divide the code for
487 each element in the switches, the code should still be easy to
490 \section2 Limitations and Differences from Java
492 We have not fully implemented every element in the Java style.
493 This way, we have reduced the amount and complexity of the code.
494 In general, the style was intended as a practical example for
495 this style overview document, and not to be a part of Qt
498 Not all widgets have every state implemented. This goes for
499 states that are common, e.g., State_Disabled. Each state is,
500 however, implemented for at least one widget.
502 We have only implemented ticks below the slider. Flat push
503 buttons are also left out. We do not handle the case where the
504 title bars and dock window titles grows to small for their
505 contents, but simply draw sub controls over each other.
507 We have not tried to emulate the Java fonts. Java and Qt use very
508 different font engines, so we don't consider it worth the effort
509 as we only use the style as an example for this overview.
511 We have hardcoded the colors (we don't use the QPalette) for
512 the linear gradients, which are used, for example, for button
513 bevels, tool bars, and check boxes. This is because the Java
514 palette cannot produce these colors. Java does not change these
515 colors based on widget color group or role anyway (they are not
516 dependent on the palette), so it does not present a problem in any
519 It is Qt's widgets that are styled. Some widgets do not exist
520 at all in Java, e.g., QToolBox. Others contain elements that the
521 Java widgets don't. The tree widget is an example of the latter in
522 which Java's JTree does not have a header.
524 The style does not handle reverse layouts. We assume that the
525 layout direction is left to right. QWindowsStyle handles reverse
526 widgets; if we implemented reverse layouts, widgets that we change
527 the position of sub elements, or handle text alignment in labels
528 our selves would need to be updated.
530 \section2 Styling Java Check Boxes
532 As an example, we will examine the styling of check boxes in the
533 java style. We describe the complete process and print all code in
534 both the java style and Qt classes involved. In the rest of this
535 document, we will not examine the source code of the individual
536 widgets. Hopefully, this will give you an idea on how to search
537 through the code if you need to check specific implementation
538 details; most widgets follow the same structure as the check
539 boxes. We have edited the QCommonStyle code somewhat to remove
540 code that is not directly relevant for check box styling.
542 We start with a look at how QCheckBox builds it style option,
543 which is QStyleOptionButton for checkboxes:
545 \snippet doc/src/snippets/code/doc_src_styles.cpp 0
547 First we let QStyleOption set up the option with the information
548 that is common for all widgets with \c initFrom(). We will look at
551 The down boolean is true when the user press the box down; this is
552 true whether the box is checked or not of the checkbox. The
553 State_NoChange state is set when we have a tristate checkbox and
554 it is partially checked. It has State_On if the box is checked and
555 State_Off if it is unchecked. State_MouseOver is set if the mouse
556 hovers over the checkbox and the widget has attribute Qt::WA_Hover
557 set - you set this in QStyle::polish(). In addition, the style
558 option also contains the text, icon, and icon size of the button.
560 \l{QStyleOption::}{initFrom()} sets up the style option with the
561 attributes that are common for all widgets. We print its
564 \snippet doc/src/snippets/code/doc_src_styles.cpp 1
566 The State_Enabled is set when the widget is enabled. When the
567 widget has focus the State_HasFocus flag is set. Equally, the
568 State_Active flag is set when the widget is a child of the active
569 window. The State_MouseOver will only be set if the widget has
570 the WA_HoverEnabled windows flag set. Notice that keypad
571 navigation must be enabled in Qt for the State_HasEditFocus to
572 be included; it is not included by default.
574 In addition to setting state flags the QStyleOption contains
575 other information about the widget: \c direction is the layout
576 direction of the layout, \c rect is the bounding rectangle of the
577 widget (the area in which to draw), \c palette is the QPalette
578 that should be used for drawing the widget, and \c fontMetrics is
579 the metrics of the font that is used by the widget.
581 We give an image of a checkbox and the style option to match
584 \image javastyle/checkboxexample.png A java style checkbox
586 The above checkbox will have the following state flags in its
615 \o State_KeyboardFocusChange
622 The QCheckBox paints itself in QWidget::paintEvent() with
623 style option \c opt and QStylePainter \c p. The QStylePainter
624 class is a convenience class to draw style elements. Most
625 notably, it wraps the methods in QStyle used for painting. The
626 QCheckBox draws itself as follows:
628 \snippet doc/src/snippets/code/doc_src_styles.cpp 2
630 QCommonStyle handles the CE_CheckBox element. The QCheckBox
631 has two sub elements: SE_CheckBoxIndicator (the checked indicator)
632 and SE_CheckBoxContents (the contents, which is used for the
633 checkbox label). QCommonStyle also implements these sub element
634 bounding rectangles. We have a look at the QCommonStyle code:
636 \snippet doc/src/snippets/code/doc_src_styles.cpp 3
638 As can be seen from the code extract, the common style gets
639 the bounding rectangles of the two sub elements of
640 CE_CheckBox, and then draws them. If the checkbox has focus,
641 the focus frame is also drawn.
643 The java style draws CE_CheckBoxIndicator, while QCommonStyle
644 handles CE_CheckboxLabel. We will examine each implementation and
645 start with CE_CheckBoxLabel:
647 \snippet doc/src/snippets/code/doc_src_styles.cpp 4
649 \l{QStyle::}{visualAlignment()} adjusts the alignment of text
650 according to the layout direction. We then draw an icon if it
651 exists, and adjust the space left for the text.
652 \l{QStyle::}{drawItemText()} draws the text taking alignment,
653 layout direction, and the mnemonic into account. It also uses the
654 palette to draw the text in the right color.
656 The drawing of labels often get somewhat involved. Luckily, it
657 can usually be handled by the base class. The java style
658 implements its own push button label since Java-contrary to
659 windows-center button contents also when the button has an icon.
660 You can examine that implementation if you need an example of
661 reimplementing label drawing.
663 We take a look at the java implementation
664 of CE_CheckBoxIndicator in \c drawControl():
666 \snippet doc/src/snippets/javastyle.cpp 0
668 We first save the state of the painter. This is not always
669 necessary but in this case the QWindowsStyle needs the painter in
670 the same state as it was when PE_IndicatorCheckBox was called (We
671 could also set the state with function calls, of course). We then
672 use \c drawButtonBackground() to draw the background of the check
673 box indicator. This is a helper function that draws the background
674 and also the frame of push buttons and check boxes. We take a look
675 at that function below. We then check if the mouse is hovering
676 over the checkbox. If it is, we draw the frame java checkboxes
677 have when the box is not pressed down and the mouse is over it.
678 You may note that java does not handle tristate boxes, so we have
681 Here we use a png image for our indicator. We could also check
682 here if the widget is disabled. We would then have to use
683 another image with the indicator in the disabled color.
685 \snippet doc/src/snippets/javastyle.cpp 1
687 We have seen how check boxes are styled in the java style from the
688 widget gets a paint request to the style is finished painting. To
689 learn in detail how each widget is painted, you need to go through
690 the code step-by-step as we have done here. However, it is
691 usually enough to know which style elements the widgets draw. The
692 widget builds a style option and calls on the style one or more
693 times to draw the style elements of which it consists. Usually,
694 it is also sufficient to know the states a widget can be in and the
695 other contents of the style option, i.e., what we list in the next
698 \section1 Widget Walkthrough
700 In this section, we will examine how most of Qt's widgets are
701 styled. Hopefully, this will save you some time and effort while
702 developing your own styles and widgets. You will not find
703 information here that is not attainable elsewhere (i.e., by
704 examining the source code or the class descriptions for the style
707 We mostly use java style widgets as examples. The java style does not
708 draw every element in the element trees. This is because they are
709 not visible for that widget in the java style. We still make sure
710 that all elements are implemented in a way that conforms with the
711 java style as custom widgets might need them (this does not
712 exclude leaving implementations to QWindowsStyle though).
714 The following is given for each widget:
717 \o A table with the members (variables, etc.) of its style option.
718 \o A table over the state flags (QStyle::StateFlag) that
719 can be set on the widget and when the states are set.
720 \o Its element tree (see section \l{The Style Elements}).
721 \o An image of the widget in which the elements are outlined.
722 \omit This is not written yet - probably never will be
724 \o List of style hints that should be checked for the
726 \o List of standard pixmaps that could be used by the
731 The element tree contains the primitive, control, and complex
732 style elements. By doing a top-down traversal of the element tree,
733 you get the sequence in which the elements should be drawn. In the
734 nodes, we have written the sub element rectangles, sub control
735 elements, and pixel metrics that should be considered when drawing
736 the element of the node.
738 Our approach on styling center on the drawing of the widgets. The
739 calculations of sub elements rectangles, sub controls, and pixel
740 metrics used \bold during drawing is only listed as contents in
741 the element trees. Note that there are rectangles and pixel
742 metrics that are only used by widgets. This leaves these
743 calculations untreated in the walkthrough. For instance, the
744 \l{QStyle::}{subControlRect()} and
745 \l{QStyle::}{sizeFromContents()} functions often call
746 \l{QStyle::}{subElementRect()} to calculate their bounding
747 rectangles. We could draw trees for this as well. However, how
748 these calculations are done is completely up to the individual
749 styles, and they do not have to follow a specific structure (Qt
750 does not impose a specific structure). You should still make sure
751 that you use the appropriate pixel metrics, though. To limit the
752 size of the document, we have therefore chosen not to include
753 trees or describe the calculations made by the Java (or any other)
756 You may be confused about how the different pixel metrics, sub
757 element rectangles, and sub control rectangles should be used when
758 examining the trees. If you are in doubt after reading the QStyle
759 enum descriptions, we suggest that you examine the QCommonStyle
760 and QWindowsStyle implementations.
762 Some of the bounding rectangles that we outline in the widget
763 images are equal. Reasons for this are that some elements draw
764 backgrounds while others draw frames and labels. If in doubt,
765 check the description of each element in QStyle. Also, some
766 elements are there to layout, i.e., decide where to draw, other
769 \section2 Common Widget Properties
771 Some states and variables are common for all widgets. These are
772 set with QStyleOption::initFrom(). Not all elements use this function;
773 it is the widgets that create the style options, and for some
774 elements the information from \l{QStyleOption::}{initFrom()} is not
777 A table with the common states follows:
785 \o Set if the widget is not disabled (see
786 QWidget::setEnabled())
789 \o Set if the widget has focus (see
792 \o State_KeyobordFocusChange
793 \o Set when the user changes focus with the keyboard
794 (see Qt::WA_KeyboardFocusChange)
797 \o Set if the mouse cursor is over the widget
800 \o Set if the widget is a child of the active window.
802 \o State_HasEditFocus
803 \o Set if the widget has the edit focus
806 The other common members for widgets are:
814 \o The bounding rectangle of the element to draw. This
815 is set to the widget bounding rectangle
819 \o The layout direction; a value of the
820 Qt::LayoutDirection enum.
823 \o The QPalette to use when drawing the element. This
824 is set to the widgets palette (QWidget::palette()).
827 \o The QFontMetrics to use when drawing text on the
831 The complex style options (classes that inherit
832 QStyleOptionComplex) used for complex style elements share two
833 variables: \l{QStyleOptionComplex::}{subControls} and
834 \l{QStyleOptionComplex::}{activeSubControls}. Both variables are
835 an OR'ed combination of QStyle::SubControl enum values. They
836 indicate which sub controls the complex control consists of and
837 which of these controls are currently active.
839 As mentioned, the style calculates the size of the widgets
840 contents, which the widgets calculate their size hints from. In
841 addition, complex controls also use the style to test which
842 sub-controls the mouse is over.
844 \section2 Widget Reference
846 Without further delay, we present the widget walkthrough; each
847 widget has its own sub-section.
849 \section3 Push Buttons
851 The style structure for push buttons is shown below. By doing a
852 top-down traversal of the tree, you get the sequence in which the
853 elements should be drawn.
855 \image javastyle/pushbutton.png The style structure for push buttons
857 The layout of the buttons, with regard element bounds, varies from
858 style to style. This makes it difficult to show conceptual images
859 of this. Also, elements may - even be intended to - have the same
860 bounds; the PE_PushButtonBevel, for instance, is used in
861 QCommonStyle to draw the elements that contains it:
862 PE_FrameDefaultButton, PE_FrameButtonBevel, and
863 PE_PanelButtonCommand, all of which have the same bounds in common
864 and windows style. PE_PushButtonBevel is also responsible for
865 drawing the menu indicator (QCommonStyle draws
866 PE_IndicatorArrowDown).
868 An image of a push button in the java style that show the bounding
869 rectangles of the elements is given below. Colors are used to
870 separate the bounding rectangles in the image; they do not fill
871 any other purpose. This is also true for similar images for the
874 \image javastyle/button.png
876 The java style, as well as all other styles implemented in Qt,
877 does not use PE_FrameButtonBevel. It is usual that a button
878 with a PE_DefaultFrame adjusts the PE_PanelButtonCommand's
879 rectangle by PM_ButtonDefaultIndicator. The CE_PushButtonLabel
880 is found by adjusting the rect by PM_DefaultFrameWidth.
882 We will now examine the style option for push
883 buttons - QStyleOptionButton. A table for the states that
884 QPushButton can set on the style option follows:
892 \o Button is down or menu is pressed shown
898 \o Button is not flat and not pressed down
901 Other members of QStyleOptionButton is:
909 \o Flags of the QStyleOptionButton::ButtonFeatures enum,
910 which describes various button properties (see enum)
913 \o The buttons QIcon (if any)
916 \o The QSize of the icon
919 \o a QString with the buttons text
922 \section3 Check and Radio Buttons
924 The structures for radio and check buttons are identical.
925 We show the structure using QCheckBox element and pixel
928 \image javastyle/checkbox.png
930 QStyleOptionButton is used as the style option for both check
931 and radio buttons. We first give a table of the states that
932 can be set in the option:
940 \o The box is pressed down
943 \o The box is partially checked (for tristate
947 \o The box is checked
950 \o The box is unchecked
953 See \l{Push Buttons} for a table over other members in the
954 QStyleOptionButtonClass.
958 In Qt, QTabBar uses the style to draw its tabs. Tabs exist either
959 in a QTabWidget, which contains a QTabBar, or as a separate bar.
960 If the bar is not part of a tab widget, it draws its own base.
962 QTabBar lays out the tabs, so the style does not have control over
963 tab placement. However, while laying out its tabs, the bar asks
964 the style for PM_TabBarTabHSpace and PM_TabBarTabVSpace, which is
965 extra width and height over the minimum size of the tab bar tab
966 label (icon and text). The style can also further influence the
967 tab size before it is laid out, as the tab bar asks for
968 CT_TabBarTab. The bounding rectangle of the bar is decided by the
969 tab widget when it is part of the widget (still considering
972 The tab bar is responsible for drawing the buttons that appear on
973 the tab bar when all tabs do not fit. Their placement is not
974 controlled by the style, but the buttons are \l{QToolButton}s
975 and are therefore drawn by the style.
977 Here is the style structure for QTabWidget and QTabBar:
979 \image javastyle/tab.png
981 The dotted lines indicate that the QTabWidget contains a tab bar,
982 but does not draw it itself, that QTabBar only draws its base line
983 when not part of a tab widget, and that the tab bar keeps two tool
984 buttons that scroll the bar when all tabs do not fit; see \l{Tool
985 Buttons} for their element tree. Also note that since the buttons
986 are children of the tab bar, they are drawn after the bar. The
987 tabs bounding rectangles overlap the base by PM_TabBarBaseOverlap.
989 Here is a tab widget in the java style:
991 \image javastyle/tabwidget.png
993 In the java style (and also windows), the tab bar shape and label
994 have the same bounding rectangle as CE_TabBarTab. Notice that the
995 tabs overlap with the tab widget frame. The base of the tab bar
996 (if drawn) is the area where the tabs and frame overlap.
998 The style option for tabs (QStyleOptionTab) contains the necessary
999 information for drawing tabs. The option contains the position of
1000 the tab in the tab bar, the position of the selected tab, the
1001 shape of the tab, the text, and icon. After Qt 4.1 the option
1002 should be cast to a QStyleOptionTabV2, which also contains the
1005 As the java style tabs don't overlap, we also present an image of
1006 a tab widget in the windows style. Note that if you want the tabs
1007 to overlap horizontally, you do that when drawing the tabs in
1008 CE_TabBarTabShape; the tabs bounding rectangles will not be
1009 altered by the tab bar. The tabs are drawn from left to right in a
1010 north tab bar shape, top to bottom in an east tab bar shape, etc.
1011 The selected tab is drawn last, so that it is easy to draw it over
1012 the other tabs (if it is to be bigger).
1014 \image javastyle/windowstabimage.png
1016 A table of the states a tab bar can set on its tabs follows:
1024 \o The tab is pressed on with the mouse.
1027 \o If it is the current tab.
1030 \o The tab bar has focus and the tab is selected
1033 Note that individual tabs may be disabled even if the tab bar
1034 is not. The tab will be active if the tab bar is active.
1036 Here follows a table of QStyleOptionTabV2's members:
1044 \o Is flags of the CornerWidget enum, which indicate
1045 if and which corner widgets the tab bar has.
1048 \o The QIcon of the tab
1051 \o The QSize of the icon
1054 \o A TabPosition enum value that indicates the tabs
1055 position on the bar relative to the other tabs.
1058 \o holds which row the tab is in
1061 \o A value of the SelectedPosition enum that indicates
1062 whether the selected tab is adjacent to or is the
1066 \o A value of the QTabBar::Shape enum indication
1067 whether the tab has rounded or triangular corners
1068 and the orientation of the tab.
1074 The frame for tab widgets use QStyleOptionTabWidgetFrame as
1075 style option. We list its members here. It does not have
1076 states set besides the common flags.
1083 \o leftCornerWidgetSize
1084 \o The QSize of the left corner widget (if any).
1086 \o rightCornerWidgetSize
1087 \o The QSize of the right corner widget (if any).
1090 \o holds the line with for drawing the panel.
1093 \o this value is currently always 0.
1096 \o The shape of the tabs on the tab bar.
1099 \o The QSize of the tab bar.
1102 \section3 Scroll Bars
1104 Here is the style structure for scrollBars:
1106 \image javastyle/scrollbar.png
1108 QScrollBar simply creates its style option and then draws
1109 CC_ScrollBar. Some styles draw the background of add page and sub
1110 page with PE_PanelButtonBevel and also use indicator arrows to
1111 draw the arrows in the nest and previous line indicators; we have
1112 not included these in the tree as their use is up to the
1113 individual style. The style's PM_MaximumDragDistance is the
1114 maximum distance in pixels the mouse can move from the bounds
1115 of the scroll bar and still move the handle.
1117 Here is an image of a scrollbar in the java style:
1119 \image javastyle/scrollbarimage.png
1121 You may notice that the scrollbar is slightly different from
1122 Java's as it has two line up indicators. We have done this to show
1123 how that you can have two separate bounding rectangles for a
1124 single sub control. The scroll bar is an example of a widget that
1125 is entirely implemented by the java style - neither QWindowsStyle
1126 nor QCommonStyle are involved in the drawing.
1128 We have a look at the different states a scroll bar can set on
1137 \o The scroll bar is horizontal
1140 The style option of QScrollBar is QStyleOptionSlider. Its
1141 members are listed in the following table. The option is used
1142 by all \l{QAbstractSlider}s; we only describe the members
1143 relevant for scroll bars here.
1151 \o the maximum value of the scroll bar
1154 \o the minimum value of the scroll bar
1157 \o the number of pixels between notches
1160 \o a value of the Qt::Orientation enum that specifies
1161 whether the scroll bar is vertical or horizontal
1164 \o the number to increase or decrease the sliders
1165 value (relative to the size of the slider and its value
1166 range) on page steps.
1169 \o the number to increase or decrease the sliders
1170 value on single (or line) steps
1173 \o The value of the slider
1176 \o the position of the slider handle. This is the same
1177 as \c sliderValue if the scroll bar is
1178 QAbstractSlider::tracking. If not, the scroll
1179 bar does not update its value before the mouse
1180 releases the handle.
1183 \o holds the direction in which the scroll bar
1184 increases its value. This is used instead of
1185 QStyleOption::direction for all abstract sliders.
1190 When calculating the sliders size hint, PM_SliderTickness and
1191 PM_SliderLength is queried from the style. As with scroll bars,
1192 the QSlider only lets the user move the handle if the mouse is
1193 within PM_MaximumDragDistance from the slider bounds. When it
1194 draws itself it creates the style option and calls \c
1195 drawComplexControl() with CC_Slider:
1197 \image javastyle/slider.png
1199 We also show a picture of a slider in the java style. We show
1200 the bounding rectangles of the sub elements as all drawing is done
1203 \image javastyle/sliderimage.png
1205 QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We
1206 present a table with the members that affect QSlider:
1214 \o the maximum value of the slider
1217 \o the minimum value of the slider
1220 \o this is the number of pixels between each notch
1223 \o a Qt::Orientation enum value that gives whether the
1224 slider is vertical or horizontal.
1227 \o a number in slider value to increase or decrease
1231 \o the number to increase or decrease the sliders
1232 value on single (or line) steps.
1235 \o the value of the slider.
1238 \o the position of the slider given as a slider value.
1239 This will be equal to the \c sliderValue if the
1240 slider is \l{QAbstractSlider::}{tracking}; if
1241 not, the sliders value will not change until the handle is
1242 released with the mouse.
1245 \o this member is used instead of QStyleOption::direction
1246 for all abstract sliders.
1249 You should note that the slider does not use direction for
1250 reverse layouts; it uses \c upsideDown.
1252 \section3 Spin Boxes
1254 When QSpinBox paints itself it creates a QStyleOptionSpinBox and
1255 asks the style to draw CC_SpinBox. The edit field is a line
1256 edit that is a child of the spin box. The dimensions of the
1257 field is calculated by the style with SC_SpinBoxEditField.
1259 Here follows the style tree for spin boxes. It is not
1260 required that a style uses the button panel primitive to paint
1261 the indicator backgrounds. You can see an image below the tree
1262 showing the sub elements in QSpinBox in the java style.
1264 \image javastyle/spinbox.png
1266 \image javastyle/spinboximage.png
1268 The QStyleOptionSpinBox, which is the style option for spin
1269 boxes. It can set the following states on the spin box.:
1277 \o Is set if one of the sub controls CC_SpinUp or
1278 CC_SpinDown is pressed on with the mouse.
1281 The rest of the members in the spin boxes style options are:
1289 \o boolean that is true if the spin box is to draw a
1293 \o Value of the ButtonSymbols enum that decides the
1294 symbol on the up/down buttons.
1297 \o A value of the StepEnabled indication which of the
1298 spin box buttons are pressed down.
1303 The title bar complex control, CC_TitleBar, is used to draw
1304 the title bars of internal windows in QMdiArea. It typically
1305 consists of a window title and close, minimize, system menu, and
1306 maximize buttons. Some styles also provide buttons for shading
1307 the window, and a button for context sensitive help.
1309 The bar is drawn in CC_TitleBar without using any sub elements.
1310 How the individual styles draw their buttons is individual, but
1311 there are standard pixmaps for the buttons that the style should
1314 \image javastyle/titlebar.png
1316 In an image over a title bar in the java style, we show the
1317 bounding rectangles of the sub elements supported by the java style
1318 (all of which are drawn with standard pixmaps). It is usual to
1319 draw the button backgrounds using PE_PanelButtonTool, but it's no
1322 \image javastyle/titlebarimage.png
1324 The style option for title bars is QStyleOptionTitleBar. It's
1333 \o The title bars icon
1336 \o the text for the title bar's label
1339 \o flags of the Qt::WindowFlag enum. The window flags
1340 used by QMdiArea for window management.
1343 \o this is the QWidget::windowState() of the window
1344 that contains the title bar.
1349 A QComboBox uses the style to draw the button and label of
1350 non-editable boxes with CC_ComboBox and CE_ComboBoxLabel.
1352 The list that pops up when the user clicks on the combo box is
1353 drawn by a \l{Delegate Classes}{delegate}, which we do not cover
1354 in this overview. You can, however, use the style to control the
1355 list's size and position with the sub element
1356 SC_ComboBoxListBoxPopup. The style also decides where the edit
1357 field for editable boxes should be with SC_ComboBoxEditField; the
1358 field itself is a QLineEdit that is a child of the combo box.
1360 \image javastyle/combobox.png
1362 We show an image over a java style combo box in which we have
1363 outlined its sub elements and sub element rectangles:
1365 \image javastyle/comboboximage.png
1367 Java combo boxes do not use the focus rect; it changes its
1368 background color when it has focus. The SC_ComboBoxEdit field is
1369 used both by QComboBox to calculate the size of the edit field and
1370 the style for calculating the size of the combo box label.
1372 The style option for combo boxes is QStyleOptionComboBox. It
1373 can set the following states:
1381 \o The box is not editable and has focus
1384 \o SC_ComboBoxArrow is active
1387 \o The container (list) of the box is visible
1390 The style options other members are:
1398 \o the icon of the current (selected) item of the
1402 \o the text of the current item in the box.
1405 \o holds whether the combo box is editable or not
1408 \o holds whether the combo box has a frame or not
1411 \o the size of the current items icon.
1414 \o the bounding rectangle of the combo box's popup
1418 \section3 Group Boxes
1420 When calculating the size hint, QGroupBox fetches three pixel
1421 metrics from the style: PM_IndicatorWidth,
1422 PM_CheckBoxLabelSpacing, and PM_IndicatorHeight. QGroupBox has
1423 the following style element tree:
1425 \image javastyle/groupbox.png
1427 Qt does not impose restrictions on how the check box is drawn; the
1428 java style draws it with CE_IndicatorCheckBox. See \l{Check and
1429 Radio Buttons} for the complete tree.
1431 We also give an image of the widget with the sub controls and
1432 sub control rectangles drawn:
1434 \image javastyle/groupboximage.png
1436 The style option for group boxes are QStyleOptionGroupBox. The
1437 following states can be set on it:
1445 \o The check box is checked
1448 \o The checkbox is pressed down
1451 \o The check box is unchecked (or there is no check box)
1454 The remaining members of QStyleOptionGroupBox are:
1462 \o flags of the QStyleOptionFrameV2::FrameFeatures
1463 enum describing the frame of the group box.
1466 \o the line width with which to draw the panel. This
1470 \o the text of the group box.
1473 \o the alignment of the group box title
1476 \o the QColor of the text
1481 As the structure of splitters are simple and do not contain any
1482 sub elements, we do not include image of splitters. CE_Splitter
1483 does not use any other elements or metrics.
1485 For its style option, Splitters uses the base class QStyleOption.
1486 It can set the following state flags on it:
1494 \o Set if it is a horizontal splitter
1497 QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its
1498 option; it sets the State_MouseOver and State_Disabled flags
1501 \section3 Progress Bar
1503 The CE_ProgressBar element is used by QProgressBar, and it is the
1504 only element used by this widget. We start with looking at the
1507 \image javastyle/progressbar.png
1509 Here is a progress bar in the windows style (the java style
1510 bounding rectangles are equal):
1512 \image javastyle/progressbarimage.png
1514 The style option for QProgressBar is QStyleOptionProgressBarV2.
1515 The bar does not set any state flags, but the other members of the
1524 \o The minimum value of the bar
1527 \o The maximum value of the bar
1530 \o The current value of the bar
1533 \o How the text is aligned in the label
1536 \o Whether the label is drawn
1542 \o Progress bars can be vertical or horizontal
1544 \o invertedAppearance
1545 \o The progress is inverted (i.e., right to left in a
1549 \o Boolean that if true, turns the label of vertical
1550 progress bars 90 degrees.
1553 \section3 Tool Buttons
1555 Tool buttons exist either independently or as part of tool bars.
1556 They are drawn equally either way. The QToolButton draws only one
1557 style element: CC_ToolButton.
1559 As you must be used to by now (at least if you have read this
1560 document sequentially), we have a tree of the widget's style
1563 \image javastyle/toolbutton.png
1565 Note that PE_FrameButtonTool and PE_IndicatorArrowDown are
1566 included in the tree as the java style draws them, but they can
1567 safely be omitted if you prefer it. The structure may also be
1568 different. QWindowsStyle, for instance, draws both
1569 PE_IndicatorButtonDropDown and PE_IndicatorArrowDown in
1572 We also have an image of a tool button where we have outlined
1573 the sub element bounding rectangles and sub controls.
1575 \image javastyle/toolbuttonimage.png
1577 Here is the states table for tool buttons:
1585 \o the tool button has the autoRise property set
1588 \o the button is not sunken (i.e., by being checked or
1589 pressed on with the mouse).
1592 \o the button is down
1595 \o the button is checkable and checked.
1598 QStyleOptionToolButton also contains the following members:
1606 \o a Qt::ArrowType enum value, which contains the
1607 direction of the buttons arrow (if an arrow is to
1608 be used in place of an icon)
1611 \o flags of the QStyleOptionToolButton::ButtonFeature
1612 enum describing if the button has an arrow, a menu,
1613 and/or has a popup-delay.
1616 \o the QFont of the buttons label
1619 \o the QIcon of the tool button
1622 \o the icon size of the button's icon
1625 \o the position of the button, as given by
1629 \o the text of the button
1632 \o a Qt::ToolButtonStyle enum value which decides
1633 whether the button shows the icon, the text, or both.
1638 Toolbars are part of the \l{QMainWindow}{main window framework}
1639 and cooperates with the QMainWindow to which it belongs while it
1640 builds its style option. A main window has 4 areas that toolbars
1641 can be placed in. They are positioned next to the four sides of
1642 the window (i.e., north, south, west, and east). Within each area
1643 there can be more than one line of toolbars; a line consists of
1644 toolbars with equal orientation (vertical or horizontal) placed
1647 \l{QToolbar}{QToolbar}s in Qt consists of three elements
1648 CE_ToolBar, PE_IndicatorToolBarHandle, and
1649 PE_IndicatorToolBarSeparator. It is QMainWindowLayout that
1650 calculates the bounding rectangles (i.e., position and size of the
1651 toolbars and their contents. The main window also uses the \c
1652 sizeHint() of the items in the toolbars when calculating the size
1655 Here is the element tree for QToolBar:
1657 \image javastyle/toolbar.png
1659 The dotted lines indicate that the QToolBar keeps an instance of
1660 QToolBarLayout and that QToolBarSeparators are kept by
1661 QToolBarLayout. When the toolbar is floating (i.e., has its own
1662 window) the PE_FrameMenu element is drawn, else QToolbar draws
1665 Here is an image of a toolbar in the java style:
1667 \image javastyle/toolbarimage.png
1669 QToolBarSaparator uses QStyleOption for their style option. It
1670 sets the State_horizontal flag if the toolbar they live in is
1671 horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}.
1673 The style option for QToolBar is QStyleOptionToolBar. The only
1674 state flag set (besides the common flags) is State_Horizontal
1675 if the bar is horizontal (i.e., in the north or south toolbar area).
1676 The member variables of the style option are:
1684 \o Holds whether the bar is movable in a value of the
1685 ToolBarFeature, which is either Movable or None.
1688 \o The width of the tool bar frame.
1691 \o This variable is currently not used and is always
1695 \o The position of the toolbar line within the toolbar
1696 area to which it belongs.
1698 \o positionWithinLine
1699 \o The position of the toolbar within the toolbar line.
1702 \o The toolbar area in which the toolbar lives.
1707 Menus in Qt are implemented in QMenu. The QMenu keeps a list of
1708 action, which it draws as menu items. When QMenu receives paint
1709 events ,it calculates the size of each menu item and draws them
1710 individually with CE_MenuItem. (Menu items do not have a separate
1711 element for their label (contents), so all drawing is done in
1712 CE_MenuItem. The menu also draws the frame of the menu with
1713 PE_FrameMenu. It also draws CE_MenuScroller if the style supports
1714 scrolling. CE_MenuTearOff is drawn if the menu is to large for its
1717 In the style structure tree, we also include QMenu as it also does
1718 styling related work. The bounding rectangles of menu items are
1719 calculated for the menus size hint and when the menu is displayed
1722 \image javastyle/menu.png
1724 The CE_MenuScroller and CE_MenuTearOff elements are handled by
1725 QCommonStyle and are not shown unless the menu is to large to fit
1726 on the screen. PE_FrameMenu is only drawn for pop-up menus.
1728 QMenu calculates rectangles based on its actions and calls
1729 CE_MenuItem and CE_MenuScroller if the style supports that.
1731 It is also usual to use PE_IndicatorCheckBox (instead of using
1732 PE_IndicatorMenuCheckMark) and PE_IndicatorRadioButton for drawing
1733 checkable menu items; we have not included them in the style tree
1734 as this is optional and varies from style to style.
1736 \image javastyle/menuimage.png
1738 The style option for menu items is QStyleOptionMenuItem. The
1739 following tables describe its state flags and other members.
1747 \o The mouse is over the action and the action is not
1751 \o The mouse is pressed down on the menu item.
1754 \o Set if the menu item is a menu scroller and it scrolls
1764 \o A value of the \l{QStyleOptionMenuItem::}{CheckType} enum,
1765 which is either NotCheckable, Exclusive, or
1769 \o Boolean that is true if the menu item is checked.
1772 \o The QFont to use for the menu item's text.
1775 \o the QIcon of the menu item.
1778 \o The maximum width allowed for the icon
1780 \o menuHasChecableItem
1781 \o Boolean which is true if at least one item in the
1785 \o The type of the menu item. This a value of the
1786 \l{QStyleOptionMenuItem::}{MenuItemType}.
1789 \o The bounding rectangle for the QMenu that the menu
1793 \o This is the distance between the text of the menu
1794 item and the shortcut.
1797 \o The text of the menu item.
1800 The setup of the style option for CE_MenuTearOff and
1801 CE_MenuScroller also uses QStyleOptionMenuItem; they only set the
1802 \c menuRect variable in addition to the common settings with
1803 QStyleOption's \l{QStyleOption::}{initFrom()}.
1807 QMenuBar uses the style to draw each menu bar item and the empty
1808 area of the menu bar. The pull-down menus themselves are
1809 \l{QMenu}s (see \l{Menus}). The style element tree for the menu
1812 \image javastyle/menubar.png
1814 The panel and empty area is drawn after the menu items. The
1815 QPainter that the QMenuBar sends to the style has the bounding
1816 rectangles of the items clipped out (i.e., clip region), so you
1817 don't need to worry about drawing over the items. The pixel
1818 metrics in QMenuBar is used when the bounding rectangles of the
1819 menu bar items are calculated.
1821 \image javastyle/menubarimage.png
1823 QStyleOptionMenuItem is used for menu bar items. The members that
1824 are used by QMenuBar is described in the following table:
1832 \o the bounding rectangle of the entire menu bar to
1833 which the item belongs.
1836 \o the text of the item
1839 \o the icon of the menu item (it is not common that
1840 styles draw this icon)
1843 QStyleOptionMenuItem is also used for drawing CE_EmptyMenuBarArea.
1845 QStyleOptionFrame is used for drawing the panel frame The
1846 \l{QStyleOptionFrame::}{lineWidth} is set to PM_MenuBarPanelWidth.
1847 The \l{QStyleOptionFrame::}{midLineWidth} is currently always set
1850 \section3 Item View Headers
1852 It is the style that draws the headers of Qt's item views. The
1853 item views keeps the dimensions on individual sections. Also
1854 note that the delegates may use the style to paint decorations
1855 and frames around items. QItemDelegate, for instance, draws
1856 PE_FrameFocusRect and PE_IndicatorViewItemCheck.
1858 \image javastyle/header.png
1860 Here is a QTableWidget showing the bounding rects of a Java
1863 \image javastyle/headerimage.png
1865 The QHeaderView uses CT_HeaderSection, PM_HeaderMargin and
1866 PM_HeaderGripMargin for size and hit test calculations. The
1867 PM_HeaderMarkSize is currently not used by Qt. QTableView draws
1868 the button in the top-left corner (i.e., the area where the
1869 vertical and horizontal headers intersect) as a CE_Header.
1871 The style option for header views is QStyleOptionHeader. The view
1872 paints one header section at a time, so the data is for the
1873 section being drawn. Its contents are:
1881 \o the icon of the header (for section that is being
1885 \o the alignment (Qt::Alignment) of the icon in the header.
1888 \o a Qt::Orientation value deciding whether the header
1889 is the horizontal header above the view or the
1890 vertical header on the left.
1893 \o a QStyleOptionHeader::SectionPosition value
1894 giving the header section's position relative to
1898 \o holds the section that is being drawn.
1901 \o a QStyleOptionHeader::SelectedPosition value giving
1902 the selected section's position relative to the
1903 section that is being painted.
1906 \o a QStyleOptionHeader::SortIndicator value that
1907 describes the direction in which the section's sort
1908 indicator should be drawn.
1911 \o the text of the currently drawn section.
1914 \o the Qt::Alignment of the text within the
1918 \section3 Tree Branch Indicators
1920 The branch indicators in a tree view is drawn by the style with
1921 PE_IndicatorBranch. We think of indicators here as the indicators
1922 that describe the relationship of the nodes in the tree. The
1923 generic QStyleOption is sent to the style for drawing this
1924 elements. The various branch types are described by states. Since
1925 there are no specific style option, we simply present the states
1934 \o the node in the tree has a sibling (i.e., there is
1935 another node in the same column).
1938 \o this branch indicator has an item.
1941 \o the branch has children (i.e., a new sub-tree can
1942 be opened at the branch).
1945 \o the branch indicator has an opened sub-tree.
1948 The tree view (and tree widget) use the style to draw the branches
1949 (or nodes if you will) of the tree.
1951 QStyleOption is used as the style for PE_IndicatorBranch has state
1952 flags set depending on what type of branch it is.
1954 Since there is no tree structure for branch indicators, we only
1955 present an image of a tree in the java style. Each state is marked
1956 in the image with a rectangle in a specific color (i.e., these
1957 rectangles are not bounding rectangles). All combinations of
1958 states you must be aware of are represented in the image.
1960 \image javastyle/branchindicatorimage.png
1962 \section3 Tool Boxes
1964 PM_SmallIconSize for sizeHints.
1966 QToolBox is a container that keeps a collection of widgets. It has
1967 one tab for each widget and display one of them at a time. The
1968 tool box lays the components it displays (the tool box buttons
1969 and selected widget) in a QVBoxLayout. The style tree for tool
1970 boxes looks like this:
1972 \image javastyle/toolbox.png
1974 We show an image of a tool box in the Plastique style:
1976 \image javastyle/toolboximage.png
1978 All elements have the same bounding rectangles in the
1979 Plastique as well as the other Qt built-in styles.
1981 The style option for tool boxes is QStyleOptionToolBox. It
1982 contains the text and icon of the tool box contents. The only
1983 state set by QToolBox is State_Sunken, which is set when the user
1984 presses a tab down with the mouse. The rest of the
1985 QStyleOptionToolBox members are:
1993 \o the icon on the toolbox tab
1996 \o the text on the toolbox tab
2001 The size grip calculates its size hint with CT_SizeGrip. The pixel
2002 metric PM_SizeGripSize is currently unused by Qt. The element tree
2003 for and an image in the Plastique style of QSizeGrip follows:
2005 \image javastyle/sizegrip.png
2007 \image javastyle/sizegripimage.png
2009 We show the size grip in a \l{QMainWindow}'s bottom right
2012 The size grip style option, QStyleOptionSizeGrip, have one
2013 member except the common members from QStyleOption:
2021 \o a Qt::Corner value that describe which corner in a
2022 window (or equivalent) the grip is located.
2025 \section3 Rubber Band
2027 The \l{QRubberBand}'s style tree consists of two nodes.
2029 \image javastyle/rubberband.png
2031 We present an image of a Java style window being moved in a
2032 QMdiArea with a rubber band:
2034 \image javastyle/rubberbandimage.png
2036 The style option for rubber bands is QStyleOptionRubberBand.
2045 \o boolean that is true if the rubber band must be
2046 drawn in an opaque style (i.e., color)
2049 \o a QRubberBand::Shape enum value that holds the
2050 shape of the band (which is either a rectangle or a
2054 \section3 Dock Widgets
2056 When the dock widget lays out its contents it asks the style for
2057 these pixel metrics: PM_DockWidgetSeparatorExtent,
2058 PM_DockWidgetTitleBarButtonMargin, PM_DockWidgetFrameWidth, and
2059 PM_DockWidgetTitleMargin. It also calculates the bounding
2060 rectangles of the float and close buttons with
2061 SE_DockWidgetCloseButton and SE_DockWidgetFloatButton.
2063 \image javastyle/dockwidget.png
2065 The dotted lines indicate that the sender keeps instances of the
2066 recipient of the arrow (i.e., it is not a style element to draw).
2067 The dock widget only draws PE_frameDockWidget when it is detached
2068 from its main window (i.e., it is a top level window). If it is
2069 docked it draws the indicator dock widget resize handle. We show a
2070 dock widget in both docked and floating state in the plastique
2073 \image javastyle/dockwidgetimage.png
2075 The style option is QStyleOptionDockWidget:
2083 \o boolean that holds whether the dock window can be
2087 \o boolean that holds whether the dock window can
2088 float (i.e., detach from the main window in which
2092 \o boolean that holds whether the window is movable
2093 (i.e., can move to other dock widget areas)
2096 \o the title text of the dock window
2099 For the buttons, QStyleOptionButton is used (see \l{Tool Buttons}
2100 for content description). The dock widget resize handle has a