Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
stylesheet.qdoc
Go to the documentation of this file.
1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page stylesheet.html
6 \title Qt Style Sheets
7 \brief How to use style sheets to customize the appearance of widgets.
8
9 \ingroup frameworks-technologies
10 \ingroup qt-basic-concepts
11 \ingroup qt-gui-concepts
12
13 \previouspage {Styles and Style Aware Widgets}{Styles}
14 \nextpage The Style Sheet Syntax
15
16 \keyword style sheet
17 \keyword stylesheet
18
19 Qt Style Sheets are a powerful mechanism that allows you to
20 customize the appearance of widgets, in addition to what is
21 already possible by subclassing QStyle. The concepts,
22 terminology, and syntax of Qt Style Sheets are heavily inspired
23 by HTML \l{http://www.w3.org/Style/CSS/}{Cascading Style Sheets
24 (CSS)} but adapted to the world of widgets.
25
26 Topics:
27
28 \list
29 \li \l{Overview}
30 \li \l{The Style Sheet Syntax}
31 \li \l{Qt Widgets Designer Integration}
32 \li \l{Customizing Qt Widgets Using Style Sheets}
33 \li \l{Qt Style Sheets Reference}
34 \li \l{Qt Style Sheets Examples}
35 \endlist
36
37 \note If Qt Style Sheets are used on the same widget as functions that
38 set the appearance of widgets, such as \l QWidget::setFont() or
39 \l QTreeWidgetItem::setBackground(), style sheets will take precedence
40 if the settings conflict.
41
42 \target overview
43 \section1 Overview
44
45 Styles sheets are textual specifications that can be set on the
46 whole application using QApplication::setStyleSheet() or on a
47 specific widget (and its children) using
48 QWidget::setStyleSheet(). If several style sheets are set at
49 different levels, Qt derives the effective style sheet from all
50 of those that are set. This is called cascading.
51
52 For example, the following style sheet specifies that all
53 \l{QLineEdit}s should use yellow as their background color, and
54 all \l{QCheckBox}es should use red as the text color:
55
56 \snippet code/doc_src_stylesheet.qdoc 0
57
58 For this kind of customization, style sheets are much more
59 powerful than QPalette. For example, it might be tempting to set
60 the QPalette::Button role to red for a QPushButton to obtain a
61 red push button. However, this wasn't guaranteed to work for all
62 styles, because style authors are restricted by the different
63 platforms' guidelines and (on Windows and \macos) by the
64 native theme engine.
65
66 Style sheets let you perform all kinds of customizations that are
67 difficult or impossible to perform using QPalette alone. If you
68 want yellow backgrounds for mandatory fields, red text for
69 potentially destructive push buttons, or fancy check boxes, style
70 sheets are the answer.
71
72 Style sheets are applied on top of the current \l{QStyle}{widget
73 style}, meaning that your applications will look as native as
74 possible, but any style sheet constraints will be taken into
75 consideration. Unlike palette fiddling, style sheets offer
76 guarantees: If you set the background color of a QPushButton to be
77 red, you can be assured that the button will have a red background
78 in all styles, on all platforms. In addition, \QD
79 provides style sheet integration, making it easy to view the effects
80 of a style sheet in different \l{QStyle}{widget styles}.
81
82 In addition, style sheets can be used to provide a distinctive
83 look and feel for your application, without having to subclass
84 QStyle. For example, you can specify arbitrary images for radio
85 buttons and check boxes to make them stand out. Using this
86 technique, you can also achieve minor customizations that would
87 normally require subclassing several style classes, such as
88 specifying a \l{QStyle::styleHint()}{style hint}.
89
90 When a style sheet is active, the QStyle returned by QWidget::style()
91 is a wrapper "style sheet" style, \e not the platform-specific style. The
92 wrapper style ensures that any active style sheet is respected and
93 otherwise forwards the drawing operations to the underlying,
94 platform-specific style (e.g., QWindowsVistaStyle on Windows).
95
96 Since Qt 4.5, Qt style sheets fully supports \macos.
97
98*/
99
100/*!
101 \page stylesheet-syntax.html
102 \previouspage Qt Style Sheets
103 \nextpage Qt Widgets Designer Integration
104 \title The Style Sheet Syntax
105
106 Qt Style Sheet terminology and syntactic rules are almost
107 identical to those of HTML CSS. If you already know CSS, you can
108 probably skim quickly through this section.
109
110 \section1 Style Rules
111
112 Style sheets consist of a sequence of style rules. A \e{style
113 rule} is made up of a selector and a declaration. The
114 \e{selector} specifies which widgets are affected by the rule;
115 the \e{declaration} specifies which properties should be set on
116 the widget. For example:
117
118 \snippet code/doc_src_stylesheet.qdoc 1
119
120 In the above style rule, \c QPushButton is the selector and \c{{
121 color: red }} is the declaration. The rule specifies that
122 QPushButton and its subclasses (e.g., \c MyPushButton) should use
123 red as their foreground color.
124
125 Qt Style Sheet is generally case insensitive (i.e., \c color,
126 \c Color, \c COLOR, and \c cOloR refer to the same property).
127 The only exceptions are class names,
128 \l{QObject::setObjectName()}{object names}, and Qt property
129 names, which are case sensitive.
130
131 Several selectors can be specified for the same declaration,
132 using commas (\c{,}) to separate the selectors. For example,
133 the rule
134
135 \snippet code/doc_src_stylesheet.qdoc 2
136
137 is equivalent to this sequence of three rules:
138
139 \snippet code/doc_src_stylesheet.qdoc 3
140
141 The declaration part of a style rule is a list of
142 \tt{\e{property}: \e{value}} pairs, enclosed in braces (\c{{}})
143 and separated with semicolons. For example:
144
145 \snippet code/doc_src_stylesheet.qdoc 4
146
147 See the \l{List of Properties} section below for the list of
148 properties provided by Qt widgets.
149
150 \section1 Selector Types
151
152 All the examples so far used the simplest type of selector, the
153 Type Selector. Qt Style Sheets support all the
154 \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{selectors
155 defined in CSS2}. The table below summarizes the most useful
156 types of selectors.
157
158 \table 100%
159 \header
160 \li Selector
161 \li Example
162 \li Explanation
163
164 \row
165 \li Universal Selector
166 \li \c *
167 \li Matches all widgets.
168
169 \row
170 \li Type Selector
171 \li \c QPushButton
172 \li Matches instances of QPushButton and of its subclasses.
173
174 \row
175 \li Property Selector
176 \li \c{QPushButton[flat="false"]}
177 \li Matches instances of QPushButton that are not
178 \l{QPushButton::}{flat}. You may use this selector to test
179 for any Qt \l{Qt's Property System}{property} that supports
180 QVariant::toString() (see the \l{QVariant::}{toString()}
181 function documentation for details). In addition, the
182 special \c class property is supported, for the name of the
183 class.
184
185 This selector may also be used to test dynamic properties.
186 For more information on customization using dynamic properties,
187 refer to \l{Customizing Using Dynamic Properties}.
188
189 Instead of \c =, you can also use \c ~= to test whether a
190 Qt property of type QStringList contains a given QString.
191
192 \warning If the value of the Qt property changes after the
193 style sheet has been set, it might be necessary to force a
194 style sheet recomputation. One way to achieve this is to
195 unset the style sheet and set it again.
196
197 \row
198 \li Class Selector
199 \li \c .QPushButton
200 \li Matches instances of QPushButton, but not of its subclasses.
201
202 This is equivalent to \c{*[class~="QPushButton"]}.
203
204 \row
205 \li ID \target ID Selector
206 Selector
207 \li \c{QPushButton#okButton}
208 \li Matches all QPushButton instances whose
209 \l{QObject::objectName}{object name} is \c okButton.
210
211 \row
212 \li Descendant Selector
213 \li \c{QDialog QPushButton}
214 \li Matches all instances of QPushButton that are descendants
215 (children, grandchildren, etc.) of a QDialog.
216
217 \row
218 \li Child Selector
219 \li \c{QDialog > QPushButton}
220 \li Matches all instances of QPushButton that are direct
221 children of a QDialog.
222 \endtable
223
224 \section1 Sub-Controls
225
226 For styling complex widgets, it is necessary to access subcontrols of the
227 widget, such as the drop-down button of a QComboBox or the up and down
228 arrows of a QSpinBox. Selectors may contain \e{subcontrols} that make it
229 possible to restrict the application of a rule to specific widget
230 subcontrols. For example:
231
232 \snippet code/doc_src_stylesheet.qdoc 5
233
234 The above rule styles the drop-down button of all \l{QComboBox}es.
235 Although the double-colon (\c{::}) syntax is reminiscent of CSS3
236 Pseudo-Elements, Qt Sub-Controls differ conceptually from these and have
237 different cascading semantics.
238
239 Sub-controls are always positioned with respect to another element - a
240 reference element. This reference element could be the widget or another
241 Sub-control. For example, the \l{Qt Style Sheets Reference#drop-down-sub}
242 {::drop-down} of a QComboBox is placed, by default, in the top right corner
243 of the Padding rectangle of the QComboBox. The
244 \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} is placed,
245 by default, in the Center of the Contents rectangle of the
246 \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} Sub-control. See
247 the \l{List of Stylable Widgets} below for the Sub-controls to use to
248 style a widget and their default positions.
249
250 The origin rectangle to be used can be changed using the
251 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}
252 property. For example, if we want to place the drop-down in the margin
253 rectangle of the QComboBox instead of the default Padding rectangle, we
254 can specify:
255
256 \snippet code/doc_src_stylesheet.qdoc 6
257
258 The alignment of the drop-down within the Margin rectangle is changed
259 using \l{Qt Style Sheets Reference#subcontrol-position-prop}
260 {subcontrol-position} property.
261
262 The \l{Qt Style Sheets Reference#width-prop}{width} and
263 \l{Qt Style Sheets Reference#height-prop}{height} properties can be used
264 to control the size of the Sub-control. Note that setting a
265 \l{Qt Style Sheets Reference#image-prop}{image} implicitly sets the size
266 of a Sub-control.
267
268 The relative positioning scheme
269 (\l{Qt Style Sheets Reference#position-prop}{position} : relative),
270 allows the position of the Sub-Control to be offset from its initial
271 position. For example, when the QComboBox's drop-down button is
272 pressed, we might like the arrow inside to be offset to give a
273 "pressed" effect. To achieve this, we can specify:
274
275 \snippet code/doc_src_stylesheet.qdoc 7
276
277 The absolute positioning scheme
278 (\l{Qt Style Sheets Reference#position-prop}{position} : absolute),
279 allows the position and size of the Sub-control to be changed with
280 respect to the reference element.
281
282 Once positioned, they are treated the same as widgets and can be styled
283 using the \l{box model}.
284
285 See the \l{List of Sub-Controls} below for a list of supported
286 sub-controls, and \l{Customizing the QPushButton's Menu Indicator
287 Sub-Control} for a realistic example.
288
289 \note With complex widgets such as QComboBox and QScrollBar, if one
290 property or sub-control is customized, \b{all} the other properties or
291 sub-controls must be customized as well.
292
293 \section1 Pseudo-States
294
295 Selectors may contain \e{pseudo-states} that denote that restrict
296 the application of the rule based on the widget's state.
297 Pseudo-states appear at the end of the selector, with a colon
298 (\c{:}) in between. For example, the following rule applies when
299 the mouse hovers over a QPushButton:
300
301 \snippet code/doc_src_stylesheet.qdoc 8
302
303 Pseudo-states can be negated using the exclamation operator. For
304 example, the following rule applies when the mouse does not hover
305 over a QRadioButton:
306
307 \snippet code/doc_src_stylesheet.qdoc 9
308
309 Pseudo-states can be chained, in which case a logical AND is
310 implied. For example, the following rule applies to when the
311 mouse hovers over a checked QCheckBox:
312
313 \snippet code/doc_src_stylesheet.qdoc 10
314
315 Negated Pseudo-states may appear in Pseudo-state chains. For example,
316 the following rule applies when the mouse hovers over a QPushButton
317 that is not pressed:
318
319 \snippet code/doc_src_stylesheet.qdoc 11
320
321 If needed, logical OR can be expressed using the comma operator:
322
323 \snippet code/doc_src_stylesheet.qdoc 12
324
325 Pseudo-states can appear in combination with subcontrols. For
326 example:
327
328 \snippet code/doc_src_stylesheet.qdoc 13
329
330 See the \l{List of Pseudo-States} section below for the list of
331 pseudo-states provided by Qt widgets.
332
333 \section1 Conflict Resolution
334
335 Conflicts arise when several style rules specify the same
336 properties with different values. Consider the following style
337 sheet:
338
339 \snippet code/doc_src_stylesheet.qdoc 14
340
341 Both rules match QPushButton instances called \c okButton and
342 there is a conflict for the \c color property. To resolve this
343 conflict, we must take into account the \e specificity of the
344 selectors. In the above example, \c{QPushButton#okButton} is
345 considered more specific than \c QPushButton, because it
346 (usually) refers to a single object, not to all instances of a
347 class.
348
349 Similarly, selectors with pseudo-states are more specific than
350 ones that do not specify pseudo-states. Thus, the following style
351 sheet specifies that a \l{QPushButton} should have white text
352 when the mouse is hovering over it, otherwise red text:
353
354 \snippet code/doc_src_stylesheet.qdoc 15
355
356 Here's a tricky one:
357
358 \snippet code/doc_src_stylesheet.qdoc 16
359
360 Here, both selectors have the same specificity, so if the mouse
361 hovers over the button while it is enabled, the second rule takes
362 precedence. If we want the text to be white in that case, we can
363 reorder the rules like this:
364
365 \snippet code/doc_src_stylesheet.qdoc 17
366
367 Alternatively, we can make the first rule more specific:
368
369 \snippet code/doc_src_stylesheet.qdoc 18
370
371 A similar issue arises in conjunction with Type Selectors.
372 Consider the following example:
373
374 \snippet code/doc_src_stylesheet.qdoc 19
375
376 Both rules apply to QPushButton instances (since QPushButton
377 inherits QAbstractButton) and there is a conflict for the
378 \l{Qt Style Sheets Reference#color-prop}{color} property. Because QPushButton
379 inherits QAbstractButton, it might be tempting to assume that
380 \c QPushButton is more specific than \c QAbstractButton. However,
381 for style sheet computations, all Type Selectors have the same
382 specificity, and the rule that appears last takes precedence. In
383 other words, \l{Qt Style Sheets Reference#color-prop}{color} is set to \c gray
384 for all \l{QAbstractButton}s, including \l{QPushButton}s. If we really
385 want \l{QPushButton}s to have red text, we can always reorder the
386 rules.
387
388 For determining the specificity of a rule, Qt Style Sheets follow
389 the
390 \l{http://www.w3.org/TR/REC-CSS2/cascade.html#specificity}{CSS2
391 Specification}:
392
393 \quotation
394 \e{A selector's specificity is calculated as follows:}
395
396 \list
397 \li \e{count the number of ID attributes in the selector (= a)}
398 \li \e{count the number of other attributes and pseudo-classes in the selector (= b)}
399 \li \e{count the number of element names in the selector (= c)}
400 \li \e{ignore pseudo-elements [i.e., \l{subcontrols}].}
401 \endlist
402
403 \e{Concatenating the three numbers a-b-c (in a number system with a
404 large base) gives the specificity.}
405
406 \e{Some examples:}
407
408 \snippet code/doc_src_stylesheet.qdoc 20
409 \endquotation
410
411 \section1 Cascading
412
413 Style sheets can be set on the QApplication, on parent widgets,
414 and on child widgets. An arbitrary widget's effective style sheet
415 is obtained by merging the style sheets set on the widget's
416 ancestors (parent, grandparent, etc.), as well as any style sheet
417 set on the QApplication.
418
419 When conflicts arise, the widget's own style sheet is always
420 preferred to any inherited style sheet, irrespective of the
421 specificity of the conflicting rules. Likewise, the parent
422 widget's style sheet is preferred to the grandparent's, etc.
423
424 One consequence of this is that setting a style rule on a widget
425 automatically gives it precedence over other rules specified in
426 the ancestor widgets' style sheets or the QApplication style
427 sheet. Consider the following example. First, we set a style
428 sheet on the QApplication:
429
430 \snippet code/doc_src_stylesheet.cpp 21
431
432 Then we set a style sheet on a QPushButton object:
433
434 \snippet code/doc_src_stylesheet.cpp 22
435
436 The style sheet on the QPushButton forces the QPushButton (and
437 any child widget) to have blue text, in spite of the more
438 specific rule set provided by the application-wide style sheet.
439
440 The result would have been the same if we had written
441
442 \snippet code/doc_src_stylesheet.cpp 23
443
444 except that if the QPushButton had children (which is unlikely),
445 the style sheet would have no impact on them.
446
447 Style sheet cascading is a complex topic. Refer to the
448 \l{http://www.w3.org/TR/CSS2/cascade.html#cascade}{CSS2
449 Specification} for the gory details. Be aware that Qt currently
450 doesn't implement \c{!important}.
451
452 \section1 Inheritance
453
454 In classic CSS, when font and color of an item is not explicitly set,
455 it gets automatically inherited from the parent. By default, when using
456 Qt Style Sheets, a widget does \b{not} automatically inherit its font
457 and color setting from its parent widget.
458
459 For example, consider a QPushButton inside a QGroupBox:
460
461 \snippet code/doc_src_stylesheet.cpp 24
462
463 The QPushButton does not have an explicit color set. Hence, instead
464 of inheriting color of its parent QGroupBox, it has the system color.
465 If we want to set the color on a QGroupBox and its children,
466 we can write:
467
468 \snippet code/doc_src_stylesheet.cpp 25
469
470 In contrast, setting a font and palette using QWidget::setFont() and
471 QWidget::setPalette() propagates to child widgets.
472
473 If you would prefer that the font and palette propagate to child widgets,
474 you can set the Qt::AA_UseStyleSheetPropagationInWidgetStyles flag, like
475 this:
476
477 Usage:
478 \snippet code/doc_src_stylesheet.cpp 96
479
480 When the widget-style font and palette propagation is enabled, font and
481 palette changes made through Qt Style Sheets will behave as if the user
482 had manually called the corresponding QWidget::setPalette() and
483 QWidget::setFont() methods on all of the QWidgets targeted by the style
484 sheet.
485
486 \list
487 \li Changes made by a style sheet are propagated.
488 They are pushed to all widgets matching the style sheet once, at the time
489 the change is made.
490 \li Changes made by calling QWidget::setPalette() or QWidget::setFont() are
491 inherited.
492 They are inherited by all existing and future children, where the respective
493 brush or font hasn't been explicitly set.
494 \endlist
495
496 \section1 Widgets Inside C++ Namespaces
497
498 The Type Selector can be used to style widgets of a particular type. For
499 example,
500
501 \snippet code/doc_src_stylesheet.cpp 26
502
503 Qt Style Sheet uses QObject::className() of the widget to determine
504 when to apply the Type Selector. When custom widgets are inside namespaces,
505 the QObject::className() returns <namespace>::<classname>. This conflicts
506 with the syntax for \l{Sub-Controls}. To overcome this problem,
507 when using the Type Selector for widgets inside namespaces, we must
508 replace the \c{::} with \c{--}. For example,
509
510 \snippet code/doc_src_stylesheet.cpp 27
511
512 \section1 Setting QObject Properties
513
514 From 4.3 and above, any designable Q_PROPERTY
515 can be set using the qproperty-<property name> syntax.
516
517 For example,
518 \snippet code/doc_src_stylesheet.qdoc 28
519
520 If the property references an enum declared with Q_ENUM, you should
521 reference its constants by name, not their numeric value.
522
523 \note Use the qproperty syntax with care, as it modifies the
524 widget that is being painted. Also, the qproperty syntax is evaluated only
525 once, which is when the widget is polished by the style. This means that any
526 attempt to use them in pseudo-states such as QPushButton:hover, will not work.
527*/
528
529/*!
530 \page stylesheet-designer.html
531 \previouspage The Style Sheet Syntax
532 \nextpage Customizing Qt Widgets Using Style Sheets
533 \title Qt Widgets Designer Integration
534
535 \l{Qt Widgets Designer Manual}{\QD} is an excellent tool
536 to preview style sheets. You can right-click on any widget in Designer
537 and select \uicontrol{Change styleSheet...} to set the style sheet.
538
539 \image designer-stylesheet-options.webp
540 {Editing a form in Qt Widgets Designer}
541
542 \QD also includes a style sheet syntax highlighter and validator. The
543 validator indicates if the syntax is valid or invalid, at the bottom left
544 of the \uicontrol{Edit Style Sheet} dialog.
545
546 \image designer-validator-highlighter.webp
547 {Editing and validating a stylesheet}
548
549 When you click \uicontrol{OK} or \uicontrol{Apply}, \QD will automatically display
550 the widget with its new stylesheet.
551
552 \image designer-stylesheet-usage.webp
553 {Preview of a form with the new stylesheet}
554 */
555
556/*!
557 \page stylesheet-customizing.html
558 \previouspage Qt Widgets Designer Integration
559 \nextpage Qt Style Sheets Reference
560 \title Customizing Qt Widgets Using Style Sheets
561
562 When using style sheets, every widget is treated as a box with four
563 concentric rectangles: the margin rectangle, the border rectangle, the
564 padding rectangle, and the content rectangle. The box model describes
565 this in further detail.
566
567 \target box model
568 \section1 The Box Model
569
570 The four concentric rectangles appear conceptually as below:
571
572 \image stylesheet-boxmodel.png
573 {Diagram of the CSS box model for layout design}
574
575 \list
576 \li The margin falls outside the border.
577 \li The border is drawn between the margin and the padding.
578 \li The padding falls inside the border, between the border and
579 the actual contents.
580 \li The content is what is left from the original widget or
581 subcontrol once we have removed the margin, the border, and
582 the padding.
583 \endlist
584
585 The \l{Qt Style Sheets Reference#margin-prop}{margin},
586 \l{Qt Style Sheets Reference#border-width-prop}
587 {border-width}, and
588 \l{Qt Style Sheets Reference#padding-prop}{padding}
589 properties all default to zero. In that case, all four rectangles
590 (\c margin, \c border, \c padding, and \c content) coincide exactly.
591
592 You can specify a background for the widget using the
593 \l{Qt Style Sheets Reference#background-image-prop}{background-image}
594 property. By default, the background-image is drawn only for the area
595 inside the border. This can be changed using the
596 \l{Qt Style Sheets Reference#background-clip-prop}{background-clip}
597 property. You can use
598 \l{Qt Style Sheets Reference#background-repeat-prop}{background-repeat}
599 and
600 \l{Qt Style Sheets Reference#background-origin-prop}{background-origin}
601 to control the repetition and origin of the background image.
602
603 A background-image does not scale with the size of the widget. To provide
604 a "skin" or background that scales along with the widget size, one must
605 use
606 \l{Qt Style Sheets Reference#border-image-prop}{border-image}. Since the
607 border-image property provides an alternate background, it is not required
608 to specify a background-image when border-image is specified. In the case,
609 when both of them are specified, the border-image draws over the
610 background-image.
611
612 In addition, the \l{Qt Style Sheets Reference#image-prop}{image} property
613 may be used to draw an image over the border-image. The image specified does
614 not tile or stretch and when its size does not match the size of the widget,
615 its alignment is specified using the
616 \l{Qt Style Sheets Reference#image-position-prop}{image-position}
617 property. Unlike background-image and border-image, one may specify a
618 SVG in the image property, in which case the image is scaled automatically
619 according to the widget size.
620
621 The steps to render a rule are as follows:
622 \list
623 \li Set clip for entire rendering operation (border-radius)
624 \li Draw the background (background-image)
625 \li Draw the border (border-image, border)
626 \li Draw overlay image (image)
627 \endlist
628
629 \target sub controls
630 \section1 Sub-controls
631
632 A widget is considered as a hierarchy (tree) of subcontrols drawn on top
633 of each other. For example, the QComboBox draws the drop-down sub-control
634 followed by the down-arrow sub-control. A QComboBox is thus rendered as
635 follows:
636 \list
637 \li Render the QComboBox { } rule
638 \li Render the QComboBox::drop-down { } rule
639 \li Render the QComboBox::down-arrow { } rule
640 \endlist
641
642 Sub-controls share a parent-child relationship. In the case of QComboBox,
643 the parent of down-arrow is the drop-down and the parent of drop-down is
644 the widget itself. Sub-controls are positioned within their parent using
645 the \l{Qt Style Sheets Reference#subcontrol-position-prop}
646 {subcontrol-position} and
647 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}
648 properties.
649
650 Once positioned, sub-controls can be styled using the \l{box model}.
651
652 \note With complex widgets such as QComboBox and QScrollBar, if one
653 property or sub-control is customized, \b{all} the other properties or
654 sub-controls must be customized as well.
655
656*/
657
658/*!
659 \page stylesheet-reference.html
660 \previouspage Customizing Qt Widgets Using Style Sheets
661 \nextpage Qt Style Sheets Examples
662 \title Qt Style Sheets Reference
663
664 Qt Style Sheets support various properties, pseudo-states, and
665 subcontrols that make it possible to customize the look of
666 widgets.
667
668 \section1 List of Stylable Widgets
669
670 The following table lists the Qt widgets that can be customized
671 using style sheets:
672
673 \table 100%
674 \header
675 \li Widget
676 \li How to Style
677
678 \row
679 \li QAbstractScrollArea \target qabstractscrollarea-widget
680 \li Supports the \l{box model}.
681 \br
682 \br
683 All derivatives of QAbstractScrollArea, including QTextEdit,
684 and QAbstractItemView (all item view classes), support
685 scrollable backgrounds using
686 \l{Qt Style Sheets Reference#background-attachment-prop}
687 {background-attachment}. Setting the background-attachment to
688 \c{fixed} provides a background-image that does not scroll with the
689 viewport. Setting the background-attachment to \c{scroll}, scrolls
690 the background-image when the scroll bars move.
691 \br
692 \br
693 See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea}
694 {Customizing QAbstractScrollArea} for an example.
695
696 \row
697 \li QCheckBox \target qcheckbox-widget
698 \li Supports the \l{box model}. The check indicator can be
699 styled using the \l{#indicator-sub}{::indicator}
700 subcontrol. By default, the indicator is placed in the Top
701 Left corner of the Contents rectangle of the widget.
702 \br
703 \br
704 The \l{#spacing-prop}{spacing} property
705 specifies the spacing between the check indicator and
706 the text.
707 \br
708 \br
709 See \l{Qt Style Sheets Examples#Customizing QCheckBox}
710 {Customizing QCheckBox} for an example.
711
712 \row
713 \li QColumnView \target qcolumnview-widget
714 \li The grip can be styled by using the \l{image-prop}{image} property.
715 \br
716 \br
717 The arrow indicators can by styled using the
718 \l{left-arrow-sub}{::left-arrow} subcontrol and the
719 \l{right-arrow-sub}{::right-arrow} subcontrol.
720
721 \row
722 \li QComboBox \target qcombobox-widget
723 \li The frame around the combobox can be styled using the
724 \l{box model}.
725 \br
726 \br
727 The drop-down button can be styled using
728 the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the
729 drop-down button is placed in the top right corner of the padding
730 rectangle of the widget.
731 \br
732 \br
733 The arrow mark inside the drop-down button
734 can be styled using the \l{#down-arrow-sub}{::down-arrow}
735 subcontrol. By default, the arrow is placed in the center of the
736 contents rectangle of the drop-down subcontrol.
737 \br
738 \br
739 The color of the placeholder text can be set using the
740 \l{#placeholder-text-color-prop}{placeholder-text-color} property.
741 \br
742 \br
743 See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox}
744 for an example.
745
746 \row
747 \li QDateEdit \target qdateedit-widget
748 \li See \l{#qspinbox-widget}{QSpinBox}.
749
750 \row
751 \li QDateTimeEdit \target qdatetimeedit-widget
752 \li See \l{#qspinbox-widget}{QSpinBox}.
753
754 \row
755 \li QDialog \target qdialog-widget
756 \li Supports only the \l{Qt Style Sheets Reference#background-prop}{background},
757 \l{#background-clip-prop}{background-clip} and
758 \l{#background-origin-prop}{background-origin} properties.
759
760 \warning Make sure you define the Q_OBJECT macro for your custom
761 widget.
762
763 \row
764 \li QDialogButtonBox \target qdialogbuttonbox-widget
765 \li The layout of buttons can be altered using the
766 \l{#button-layout-prop}{button-layout} property.
767
768 \row
769 \li QDockWidget \target qdockwidget-widget
770 \li Supports styling of the title bar and the title bar buttons when docked.
771 \br
772 \br
773 The dock widget border can be styled using the \l{#border-prop}{border}
774 property. The \l{#title-sub}{::title} subcontrol can be used to customize
775 the title bar. The close and float buttons are positioned with respect
776 to the \l{title-sub}{::title} subcontrol using the
777 \l{#close-button-sub}{::close-button} and
778 \l{#float-button-sub}{::float-button} respectively.
779 \br
780 \br
781 When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo
782 class is set. In addition, depending on QDockWidget::DockWidgetFeature,
783 the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and
784 \l{#movable-ps}{:movable} pseudo states are set.
785
786 \note Use QMainWindow::separator to style the resize handle.
787
788 \warning The style sheet has no effect when the QDockWidget is undocked
789 as Qt uses native top level windows when undocked.
790
791 See \l{Qt Style Sheets Examples#Customizing QDockWidget}
792 {Customizing QDockWidget} for an example.
793
794 \row
795 \li QDoubleSpinBox \target qdoublespinbox-widget
796 \li See \l{#qspinbox-widget}{QSpinBox}.
797
798 \row
799 \li QFrame \target qframe-widget
800 \li Supports the \l{box model}.
801 \br
802 \br
803 Since 4.3, setting a stylesheet on a QLabel automatically
804 sets the QFrame::frameStyle property to QFrame::StyledPanel.
805 \br
806 \br
807 See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame}
808 for an example.
809
810 \row
811 \li QGroupBox \target qgroupbox-widget
812 \li Supports the \l{box model}.
813 \br
814 \br
815 The title can be styled using the
816 \l{#title-sub}{::title} subcontrol. By default, the title is placed
817 depending on QGroupBox::textAlignment.
818 \br
819 \br
820 In the case of a checkable QGroupBox, the title includes the
821 check indicator. The indicator is styled using the
822 \l{#indicator-sub}{::indicator} subcontrol. The
823 \l{#spacing-prop}{spacing} property can be used to control
824 the spacing between the text and indicator.
825 \br
826 \br
827 See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox}
828 for an example.
829
830 \row
831 \li QHeaderView \target qheaderview-widget
832 \li Supports the \l{box model}.
833 \br
834 \br
835 The sections of the header view are
836 styled using the \l{#section-sub}{::section} sub control. The
837 \c{section} Sub-control supports the \l{#middle-ps}{:middle},
838 \l{#first-ps}{:first}, \l{#last-ps}{:last},
839 \l{#only-one-ps}{:only-one}, \l{#next-selected-ps}{:next-selected},
840 \l{#previous-selected-ps}{:previous-selected},
841 \l{#selected-ps}{:selected},
842 and \l{#checked-ps}{:checked} pseudo states.
843 \br
844 \br
845 The sort indicator can be styled using the
846 \l{#up-arrow-sub}{::up-arrow} and the
847 \l{#down-arrow-sub}{::down-arrow} Sub-control.
848 \br
849 \br
850 See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView}
851 for an example.
852
853 \row
854 \li QLabel \target qlabel-widget
855 \li Supports the \l{box model}. Does not support the
856 \l{#hover-ps}{:hover} pseudo-state.
857 \br
858 \br
859 Since 4.3, setting a stylesheet on a QLabel automatically
860 sets the QFrame::frameStyle property to QFrame::StyledPanel.
861 \br
862 \br
863 See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an
864 example (a QLabel derives from QFrame).
865
866 \row
867 \li QLineEdit \target qlineedit-widget
868 \li Supports the \l{box model}.
869 \br
870 \br
871 The color and background of the selected item is styled using
872 \l{#selection-color-prop}{selection-color} and
873 \l{#selection-background-color-prop}{selection-background-color}
874 respectively.
875 \br
876 \br
877 The color of the placeholder text can be set using the
878 \l{#placeholder-text-color-prop}{placeholder-text-color} property.
879 \br
880 \br
881 The password character can be styled using the
882 \l{#lineedit-password-character-prop}{lineedit-password-character}
883 property.
884 \br
885 \br
886 The password mask delay can be changed using the
887 \l{#lineedit-password-mask-delay-prop}{lineedit-password-mask-delay}
888 \br
889 \br
890 See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit}
891 for an example.
892
893 \row
894 \li QListView \target qlistview-widget
895 \li Supports the \l{box model}.
896 \br
897 \br
898 When
899 \l{QAbstractItemView::alternatingRowColors}{alternating row colors}
900 is enabled, the alternating colors can be styled using the
901 \l{#alternate-background-color-prop}{alternate-background-color}
902 property.
903 \br
904 \br
905 The color and background of the selected item is styled using
906 \l{#selection-color-prop}{selection-color} and
907 \l{#selection-background-color-prop}{selection-background-color}
908 respectively.
909 \br
910 \br
911 The selection behavior is controlled by the
912 \l{#show-decoration-selected-prop}{show-decoration-selected} property.
913 \br
914 \br
915 Use the \l{#item-sub}{::item} subcontrol for more fine grained
916 control over the items in the QListView.
917 \br
918 \br
919 See \l{qabstractscrollarea-widget}{QAbstractScrollArea} to
920 style scrollable backgrounds.
921 \br
922 \br
923 See \l{Qt Style Sheets Examples#Customizing QListView}
924 {Customzing QListView} for an example.
925
926 \row
927 \li QListWidget \target qlistwidget-widget
928 \li See \l{#qlistview-widget}{QListView}.
929
930 \row
931 \li QMainWindow \target qmainwindow-widget
932 \li Supports styling of the separator.
933 \br
934 \br
935 The separator in a QMainWindow when using QDockWidget is styled
936 using the \l{#separator-sub}{::separator} subcontrol.
937 \br
938 \br
939 See \l{Qt Style Sheets Examples#Customizing QMainWindow}{Customizing QMainWindow}
940 for an example.
941
942 \row
943 \li QMenu \target qmenu-widget
944 \li Supports the \l{box model}.
945 \br
946 \br
947 Individual items are styled using the \l{#item-sub}{::item}
948 subcontrol. In addition to the usually supported pseudo states,
949 \c{item} subcontrol supports the
950 \l{#selected-ps}{:selected}, \l{#default-ps}{:default},
951 \l{#exclusive-ps}{:exclusive} and the
952 \l{#non-exclusive-ps}{non-exclusive} pseudo states.
953 \br
954 \br
955 The indicator of checkable menu items is styled using the
956 \l{#indicator-sub}{::indicator} subcontrol.
957 \br
958 \br
959 The separator is styled using the \l{#separator-sub}{::separator}
960 subcontrol.
961 \br
962 \br
963 For items with a sub menu, the arrow marks are styled using the
964 \l{right-arrow-sub}{right-arrow} and
965 \l{left-arrow-sub}{left-arrow}.
966 \br
967 \br
968 The scroller is styled using the \l{#scroller-sub}{::scroller}.
969 \br
970 \br
971 The tear-off is styled using the \l{#tearoff-sub}{::tearoff}.
972 \br
973 \br
974 See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu}
975 for an example.
976
977 \row
978 \li QMenuBar \target qmenubar-widget
979 \li Supports the \l{box model}.
980 \br
981 \br
982 The \l{#spacing-prop}{spacing}
983 property specifies the spacing between menu items.
984 Individual items are styled using the \l{#item-sub}{::item}
985 subcontrol.
986
987 \warning When running on Qt/Mac, the menu bar is usually embedded into the
988 system-wide menu bar. In this case, the style sheet will have no effect.
989
990 See \l{Qt Style Sheets Examples#Customizing QMenuBar}{Customizing QMenuBar}
991 for an example.
992
993 \row
994 \li QMessageBox \target qmessagebox-widget
995 \li The \l{#messagebox-text-interaction-flags-prop}
996 {messagebox-text-interaction-flags} property can be used to alter
997 the interaction with text in the message box.
998
999 \row
1000 \li QProgressBar \target qprogressbar-widget
1001 \li Supports the \l{box model}.
1002 \br
1003 \br
1004 The chunks of the progress bar
1005 can be styled using the \l{#chunk-sub}{::chunk} subcontrol.
1006 The chunk is displayed on the Contents rectangle of the widget.
1007 \br
1008 \br
1009 If the progress bar displays text, use the \l{text-align-prop}{text-align}
1010 property to position the text.
1011 \br
1012 \br
1013 Indeterminate progress bars have the
1014 \l{#indeterminate-ps}{:indeterminate} pseudo state set.
1015 \br
1016 \br
1017 See \l{Qt Style Sheets Examples#Customizing QProgressBar}{Customizing QProgressBar}
1018 for an example.
1019
1020 \row
1021 \li QPushButton \target qpushbutton-widget
1022 \li Supports the \l{box model}.
1023 \br
1024 \br
1025 Supports the \l{#default-ps}{:default},
1026 \l{#flat-ps}{:flat}, \l{#checked-ps}{:checked} pseudo states.
1027 \br
1028 \br
1029 Since 5.15, the \l{#icon-prop}{icon} property can be set to
1030 override the button icon.
1031 \br
1032 \br
1033 For QPushButton with a menu, the menu indicator is styled
1034 using the \l{#menu-indicator-sub}{::menu-indicator}
1035 subcontrol. Appearance of checkable push buttons can be
1036 customized using the \l{#open-ps}{:open} and
1037 \l{#closed-ps}{:closed} pseudo-states.
1038
1039 \warning If you only set a background-color on a QPushButton, the background
1040 may not appear unless you set the border property to some value. This is
1041 because, by default, the QPushButton draws a native border which completely
1042 overlaps the background-color. For example,
1043
1044 \snippet code/doc_src_stylesheet.qdoc 30
1045
1046 See \l{Qt Style Sheets Examples#Customizing QPushButton}{Customizing QPushButton}
1047 for an example.
1048
1049 \row
1050 \li QRadioButton \target qradiobutton-widget
1051 \li Supports the \l{box model}.
1052 \br
1053 \br
1054 The check indicator can be
1055 styled using the \l{#indicator-sub}{::indicator}
1056 subcontrol. By default, the indicator is placed in the Top
1057 Left corner of the Contents rectangle of the widget.
1058 \br
1059 \br
1060 The \l{#spacing-prop}{spacing} property
1061 specifies the spacing between the check indicator and
1062 the text.
1063 \br
1064 \br
1065 See \l{Qt Style Sheets Examples#Customizing QRadioButton}
1066 {Customizing QRadioButton} for an example.
1067
1068 \row
1069 \li QScrollBar \target qscrollbar-widget
1070 \li Supports the \l{box model}.
1071 \br
1072 \br
1073 The Contents rectangle of the widget
1074 is considered to be the groove over which the slider moves. The extent
1075 of the QScrollBar (i.e the width or the height depending on the orientation)
1076 is set using the \l{#width-prop}{width} or \l{#height-prop}{height} property
1077 respectively. To determine the orientation, use the
1078 \l{#horizontal-ps}{:horizontal} and the \l{vertical-ps}{:vertical}
1079 pseudo states.
1080 \br
1081 \br
1082 The slider can be styled using the \l{#handle-sub}{::handle} subcontrol.
1083 Setting the \l{#min-width-prop}{min-width} or \l{#min-height-prop}{min-height}
1084 provides size constraints for the slider depending on the orientation.
1085 \br
1086 \br
1087 The \l{add-line-sub}{::add-line} subcontrol can be used to style the
1088 button to add a line. By default, the add-line subcontrol is placed in
1089 top right corner of the Border rectangle of the widget. Depending on the
1090 orientation the \l{#right-arrow-sub}{::right-arrow} or
1091 \l{#down-arrow-sub}{::down-arrow}. By default, the arrows are placed in
1092 the center of the Contents rectangle of the add-line subcontrol.
1093 \br
1094 \br
1095 The \l{sub-line-sub}{::sub-line} subcontrol can be used to style the
1096 button to subtract a line. By default, the sub-line subcontrol is placed in
1097 bottom right corner of the Border rectangle of the widget. Depending on the
1098 orientation the \l{#left-arrow-sub}{::left-arrow} or
1099 \l{#up-arrow-sub}{::up-arrow}. By default, the arrows are placed in
1100 the center of the Contents rectangle of the sub-line subcontrol.
1101 \br
1102 \br
1103 The \l{sub-page-sub}{::sub-page} subcontrol can be used to style the
1104 region of the slider that subtracts a page. The \l{add-page-sub}{::add-page}
1105 subcontrol can be used to style the region of the slider that adds a page.
1106 \br
1107 \br
1108 See \l{Qt Style Sheets Examples#Customizing QScrollBar}{Customizing QScrollBar}
1109 for an example.
1110
1111 \row
1112 \li QSizeGrip \target qsizegrip-widget
1113 \li Supports the \l{#width-prop}{width},
1114 \l{#height-prop}{height}, and \l{#image-prop}{image}
1115 properties.
1116 \br
1117 \br
1118 See \l{Qt Style Sheets Examples#Customizing QSizeGrip}{Customizing QSizeGrip}
1119 for an example.
1120
1121 \row
1122 \li QSlider \target qslider-widget
1123 \li Supports the \l{box model}.
1124 \br
1125 \br
1126 For horizontal slides, the
1127 \l{min-width-prop}{min-width} and \l{height-prop}{height}
1128 properties must be provided. For vertical sliders, the
1129 \l{min-height-prop}{min-height} and \l{width-prop}{width}
1130 properties must be provided.
1131 \br
1132 \br
1133 The groove of the slider is styled
1134 using the \l{#groove-sub}{::groove}. The groove is
1135 positioned by default in the Contents rectangle of the widget.
1136 The thumb of the slider is styled using \l{#handle-sub}{::handle}
1137 subcontrol. The subcontrol moves in the Contents rectangle of
1138 the groove subcontrol.
1139 \br
1140 \br
1141 See \l{Qt Style Sheets Examples#Customizing QSlider}{Customizing QSlider}
1142 for an example.
1143
1144 \row
1145 \li QSpinBox \target qspinbox-widget
1146 \li The frame of the spin box can be styled using the \l{box
1147 model}.
1148 \br
1149 \br
1150 The up button and arrow can be styled using the
1151 \l{#up-button-sub}{::up-button} and
1152 \l{#up-arrow-sub}{::up-arrow} subcontrols. By default,
1153 the up-button is placed in the top right corner in the
1154 Padding rectangle of the widget. Without an explicit size,
1155 it occupies half the height of its reference rectangle.
1156 The up-arrow is placed in the center of the Contents
1157 rectangle of the up-button.
1158 \br
1159 \br
1160 The down button and arrow can be styled using the
1161 \l{#down-button-sub}{::down-button} and
1162 \l{#down-arrow-sub}{::down-arrow} subcontrols. By default,
1163 the down-button is placed in the bottom right corner in the
1164 Padding rectangle of the widget. Without an explicit size,
1165 it occupies half the height of its reference rectangle.
1166 The bottom-arrow is placed in the center of the Contents
1167 rectangle of the bottom-button.
1168 \br
1169 \br
1170 See \l{Qt Style Sheets Examples#Customizing QSpinBox}{Customizing QSpinBox}
1171 for an example.
1172
1173 \row
1174 \li QSplitter \target qsplitter-widget
1175 \li Supports the \l{box model}. The handle of the splitter
1176 is styled using the \l{#handle-sub}{::handle} subcontrol.
1177 \br
1178 \br
1179 See \l{Qt Style Sheets Examples#Customizing QSplitter}{Customizing QSplitter}
1180 for an example.
1181
1182 \row
1183 \li QStatusBar \target qstatusbar-widget
1184 \li Supports only the \l{Qt Style Sheets Reference#background-prop}
1185 {background} property.
1186 The frame for individual items can be style using the
1187 \l{#item-sub}{::item} subcontrol.
1188 \br
1189 \br
1190 See \l{Qt Style Sheets Examples#Customizing QStatusBar}{Customizing QStatusBar}
1191 for an example.
1192
1193 \row
1194 \li QTabBar \target qtabbar-widget
1195 \li Individual tabs may be styled using the \l{#tab-sub}{::tab} subcontrol.
1196 Close buttons using the \l{#close-button-sub}{::close-button}.
1197 The tabs support the
1198 \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first},
1199 \l{#last-ps}{:last}, \l{#middle-ps}{:middle},
1200 \l{#previous-selected-ps}{:previous--selected},
1201 \l{#next-selected-ps}{:next-selected},
1202 \l{#selected-ps}{:selected} pseudo states.
1203 \br
1204 \br
1205 The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right},
1206 \l{#bottom-ps}{:bottom} pseudo states depending on the orientation
1207 of the tabs.
1208 \br
1209 \br
1210 Overlapping tabs for the selected state are created by using
1211 negative margins or using the \c{absolute} position scheme.
1212 \br
1213 \br
1214 The tear indicator of the QTabBar is styled using the
1215 \l{#tear-sub}{::tear} subcontrol.
1216 \br
1217 \br
1218 QTabBar used two QToolButtons for its scrollers that can be styled
1219 using the \c{QTabBar QToolButton} selector. To specify the width
1220 of the scroll button use the \l{#scroller-sub}{::scroller}
1221 subcontrol.
1222 \br
1223 \br
1224 The alignment of the tabs within the QTabBar is styled
1225 using the \l{#Alignment}{alignment} property.
1226 \br
1227 \warning
1228 To change the position of the QTabBar within a QTabWidget, use the
1229 \l{#tab-bar-sub}{tab-bar} subcontrol (and set subcontrol-position).
1230
1231 See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar}{Customizing QTabBar}
1232 for an example.
1233
1234 \row
1235 \li QTabWidget \target qtabwidget-widget
1236 \li The frame of the tab widget is styled using the
1237 \l{#pane-sub}{::pane} subcontrol. The left and right
1238 corners are styled using the \l{#left-corner-sub}{::left-corner}
1239 and \l{#right-corner-sub}{::right-corner} respectively.
1240 The position of the tab bar is controlled using the
1241 \l{#tab-bar-sub}{::tab-bar} subcontrol.
1242 \br
1243 \br
1244 By default, the subcontrols have positions of a QTabWidget in
1245 the QWindowsStyle. To place the QTabBar in the center, set the
1246 subcontrol-position of the tab-bar subcontrol.
1247 \br
1248 \br
1249 The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right},
1250 \l{#bottom-ps}{:bottom} pseudo states depending on the orientation
1251 of the tabs.
1252 \br
1253 \br
1254 See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar}
1255 {Customizing QTabWidget} for an example.
1256
1257 \row
1258 \li QTableView \target qtableview-widget
1259 \li Supports the \l{box model}. When
1260 \l{QAbstractItemView::alternatingRowColors}{alternating row colors}
1261 is enabled, the alternating colors can be styled using the
1262 \l{#alternate-background-color-prop}{alternate-background-color}
1263 property.
1264 \br
1265 \br
1266 The color and background of the selected item is styled using
1267 \l{#selection-color-prop}{selection-color} and
1268 \l{#selection-background-color-prop}{selection-background-color}
1269 respectively.
1270 \br
1271 \br
1272 The corner widget in a QTableView is implemented as a QAbstractButton
1273 and can be styled using the "QTableView QTableCornerButton::section"
1274 selector.
1275 \br
1276 \warning If you only set a background-color on a QTableCornerButton,
1277 the background may not appear unless you set the border property to
1278 some value. This is because, by default, the QTableCornerButton draws a
1279 native border which completely overlaps the background-color.
1280
1281 \br
1282 The color of the grid can be specified using the
1283 \l{#gridline-color-prop}{gridline-color} property.
1284 \br
1285 \br
1286 See \l{qabstractscrollarea-widget}{QAbstractScrollArea} to
1287 style scrollable backgrounds.
1288 \br
1289 \br
1290 See \l{Qt Style Sheets Examples#Customizing QTableView}
1291 {Customzing QTableView} for an example.
1292
1293 \row
1294 \li QTableWidget \target qtablewidget-widget
1295 \li See \l{#qtableview-widget}{QTableView}.
1296
1297 \row
1298 \li QTextEdit \target qtextedit-widget
1299 \li Supports the \l{box model}.
1300 \br
1301 \br
1302 The color and background of selected text is styled using
1303 \l{#selection-color-prop}{selection-color} and
1304 \l{#selection-background-color-prop}{selection-background-color}
1305 respectively.
1306 \br
1307 \br
1308 The color of the placeholder text can be set using the
1309 \l{#placeholder-text-color-prop}{placeholder-text-color} property.
1310 \br
1311 \br
1312 See \l{qabstractscrollarea-widget}{QAbstractScrollArea} to
1313 style scrollable backgrounds.
1314
1315 \row
1316 \li QTimeEdit \target qtimeedit-widget
1317 \li See \l{#qspinbox-widget}{QSpinBox}.
1318
1319 \row
1320 \li QToolBar \target qtoolbar-widget
1321 \li Supports the \l{box model}.
1322 \br
1323 \br
1324 The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right},
1325 \l{#bottom-ps}{:bottom} pseudo states depending on the area in
1326 which the tool bar is grouped.
1327 \br
1328 \br
1329 The \l{#first-ps}{:first}, \l{#last-ps}{:last}, \l{#middle-ps}{:middle},
1330 \l{#only-one-ps}{:only-one} pseudo states indicator the position
1331 of the tool bar within a line group (See
1332 QStyleOptionToolBar::positionWithinLine).
1333 \br
1334 \br
1335 The separator of a QToolBar is styled using the
1336 \l{#separator-sub}{::separator} subcontrol.
1337 \br
1338 \br
1339 The handle (to move the toolbar) is styled using the
1340 \l{#handle-sub}{::handle} subcontrol.
1341 \br
1342 \br
1343 See \l{Qt Style Sheets Examples#Customizing QToolBar}{Customizing QToolBar}
1344 for an example.
1345
1346 \row
1347 \li QToolBox \target qtoolbox-widget
1348 \li Supports the \l{box model}.
1349 \br
1350 \br
1351 The individual tabs can by styled using the
1352 \l{#tab-sub}{::tab} subcontrol. The tabs support the
1353 \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first},
1354 \l{#last-ps}{:last}, \l{#middle-ps}{:middle},
1355 \l{#previous-selected-ps}{:previous-selected},
1356 \l{#next-selected-ps}{:next-selected},
1357 \l{#selected-ps}{:selected} pseudo states.
1358
1359 \row
1360 \li QToolButton \target qtoolbutton-widget
1361 \li Supports the \l{box model}.
1362 \br
1363 \br
1364 If the QToolButton has a menu, is
1365 \l{#menu-indicator-sub}{::menu-indicator} subcontrol can be used to
1366 style the indicator. By default, the menu-indicator is positioned
1367 at the bottom right of the Padding rectangle of the widget.
1368 \br
1369 \br
1370 If the QToolButton is in QToolButton::MenuButtonPopup mode,
1371 the \l{#menu-button-sub}{::menu-button} subcontrol is used to draw the
1372 menu button. \l{#menu-arrow-sub}{::menu-arrow} subcontrol is used to
1373 draw the menu arrow inside the menu-button. By default, it is
1374 positioned in the center of the Contents rectangle of the
1375 menu-button subcontrol.
1376 \br
1377 \br
1378 When the QToolButton displays arrows, the \l{#up-arrow-sub}{::up-arrow},
1379 \l{#down-arrow-sub}{::down-arrow}, \l{#left-arrow-sub}{::left-arrow}
1380 and \l{#right-arrow-sub}{::right-arrow} subcontrols are used.
1381 \br
1382 \warning If you only set a background-color on a QToolButton, the background
1383 will not appear unless you set the border property to some value. This is
1384 because, by default, the QToolButton draws a native border which completely
1385 overlaps the background-color. For example,
1386
1387 \snippet code/doc_src_stylesheet.qdoc 31
1388
1389 See \l{Qt Style Sheets Examples#Customizing QToolButton}{Customizing QToolButton}
1390 for an example.
1391
1392 \row
1393 \li QToolTip \target qtooltip-widget
1394 \li Supports the \l{box model}. The \l{#opacity-prop}{opacity}
1395 property controls the opacity of the tooltip.
1396 \br
1397 \br
1398 See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame}
1399 for an example (a QToolTip is a QFrame).
1400
1401 \row
1402 \li QTreeView \target qtreeview-widget
1403 \li Supports the \l{box model}. When
1404 \l{QAbstractItemView::alternatingRowColors}{alternating row colors}
1405 is enabled, the alternating colors can be styled using the
1406 \l{#alternate-background-color-prop}{alternate-background-color}
1407 property.
1408 \br
1409 \br
1410 The color and background of the selected item is styled using
1411 \l{#selection-color-prop}{selection-color} and
1412 \l{#selection-background-color-prop}{selection-background-color}
1413 respectively.
1414 \br
1415 \br
1416 The selection behavior is controlled by the
1417 \l{#show-decoration-selected-prop}{show-decoration-selected} property.
1418 \br
1419 \br
1420 The branches of the tree view can be styled using the
1421 \l{#branch-sub}{::branch} subcontrol. The
1422 ::branch Sub-control supports the \l{open-ps}{:open},
1423 \l{closed-ps}{:closed}, \l{has-siblings-ps}{:has-sibling} and
1424 \l{has-children-ps}{:has-children} pseudo states.
1425 \br
1426 \br
1427 Use the \l{#item-sub}{::item} subcontrol for more fine grained
1428 control over the items in the QTreeView.
1429 \br
1430 \br
1431 See \l{qabstractscrollarea-widget}{QAbstractScrollArea} to
1432 style scrollable backgrounds.
1433 \br
1434 \br
1435 See \l{Qt Style Sheets Examples#Customizing QTreeView}{Customizing QTreeView}
1436 for an example to style the branches.
1437
1438 \row
1439 \li QTreeWidget \target qtreewidget-widget
1440 \li See \l{#qtreeview-widget}{QTreeView}.
1441
1442 \row
1443 \li QWidget \target qwidget-widget
1444 \li Supports only the \l{Qt Style Sheets Reference#background-prop}{background},
1445 \l{#background-clip-prop}{background-clip} and
1446 \l{#background-origin-prop}{background-origin} properties.
1447 \br
1448 \br
1449 If you subclass from QWidget, you need to provide a paintEvent for your
1450 custom QWidget as below:
1451 \snippet code/doc_src_stylesheet.cpp 32
1452
1453 The above code is a no-operation if there is no stylesheet set.
1454
1455 \warning Make sure you define the Q_OBJECT macro for your custom
1456 widget.
1457
1458 \endtable
1459
1460 \section1 List of Properties
1461
1462 This section lists all the properties supported by Qt Style
1463 Sheets. Which values can be given to a property depend on the
1464 \l{List of Property Types}{property's type}. Unless otherwise
1465 specified, the following properties apply to all widgets. Properties
1466 marked with an asterisk * are specific to Qt and have no equivalent
1467 in CSS2 or CSS3. The Qt-specific properties are the following:
1468 \list
1469 \li \l{#gridline-color*}{gridline-color*}
1470 \li \l{#image*}{image*}
1471 \li \l{#lineedit-password-character*}{lineedit-password-character*}
1472 \li \l{#lineedit-password-mask-delay*}{lineedit-password-mask-delay*}
1473 \li \l{#messagebox-text-interaction-flags*}{messagebox-text-interaction-flags*}
1474 \li \l{#opacity*}{opacity*}
1475 \li \l{#placeholder-text-color*}{placeholder-text-color*}
1476 \li \l{#selection-background-color*}{selection-background-color*}
1477 \li \l{#selection-color*}{selection-color*}
1478 \li \l{#show-decoration-selected*}{show-decoration-selected*}
1479 \li \l{#spacing*}{spacing*}
1480 \li \l{#subcontrol-origin*}{subcontrol-origin*}
1481 \li \l{#subcontrol-position*}{subcontrol-position*}
1482 \li \l{#widget-animation-duration*}{widget-animation-duration*}
1483 \endlist
1484
1485 \section2 accent-color
1486
1487 \table
1488 \row \li \b Type \li \l{#Brush}{Brush}
1489 \endtable
1490
1491 The property sets the \c Accent, which is used to emphasize
1492 interactive UI elements. If this property is not set, it defaults to the \c highlight color.
1493
1494 \section2 alternate-background-color
1495 \target alternate-background-color-prop
1496 \table
1497 \row \li \b Type \li \l{#Brush}{Brush}
1498 \endtable
1499 The \l{QAbstractItemView::alternatingRowColors}
1500 {alternate background color} used in QAbstractItemView subclasses.
1501
1502 If this property is not set, the default value is
1503 whatever is set for the palette's
1504 \l{QPalette::}{AlternateBase} role.
1505
1506 Example:
1507
1508 \snippet code/doc_src_stylesheet.qdoc 33
1509
1510 See also \l{Qt Style Sheets Reference#background-prop}{background} and
1511 \l{#selection-background-color-prop}{selection-background-color}.
1512
1513 \section2 background
1514 \target background-prop
1515 \table
1516 \row \li \b Type \li \l{#Background}{Background}
1517 \endtable
1518 Shorthand notation for setting the background. Equivalent
1519 to specifying \c background-color, \c background-image, \c
1520 background-repeat, and/or \c background-position.
1521
1522 This property is supported by QAbstractItemView
1523 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1524 QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit,
1525 QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter,
1526 QTextEdit, QToolTip, and plain \l{QWidget}s.
1527
1528 Example:
1529
1530 \snippet code/doc_src_stylesheet.qdoc 34
1531
1532
1533 Often, it is required to set a fill pattern similar to the styles
1534 in Qt::BrushStyle. You can use the background-color property for
1535 Qt::SolidPattern, Qt::RadialGradientPattern, Qt::LinearGradientPattern
1536 and Qt::ConicalGradientPattern. The other patterns are easily achieved
1537 by creating a background image that contains the pattern.
1538
1539 Example:
1540
1541 \snippet code/doc_src_stylesheet.qdoc 35
1542
1543 See also \l{#background-origin-prop}{background-origin},
1544 \l{#selection-background-color-prop}{selection-background-color},
1545 \l{#background-clip-prop}{background-clip},
1546 \l{#background-attachment-prop}{background-attachment}
1547 and \l{#alternate-background-color-prop}{alternate-background-color}.
1548
1549 \section2 background-color
1550 \target background-color-prop
1551 \table
1552 \row \li \b Type \li \l{#Brush}{Brush}
1553 \endtable
1554 The background color used for the widget.
1555
1556 Examples:
1557
1558 \snippet code/doc_src_stylesheet.qdoc 36
1559
1560 \section2 background-image
1561 \target background-image-prop
1562 \table
1563 \row \li \b Type \li \l{#Url}{Url}
1564 \endtable
1565 The background image used for the widget. Semi-transparent
1566 parts of the image let the \c background-color shine
1567 through.
1568
1569 Example:
1570
1571 \snippet code/doc_src_stylesheet.qdoc 37
1572
1573
1574 \section2 background-repeat
1575 \target background-repeat-prop
1576 \table
1577 \row \li \b Type \li \l{#Repeat}{Repeat}
1578 \endtable
1579 Whether and how the background image is repeated to fill
1580 the \c background-origin rectangle.
1581
1582 If this property is not specified, the background image
1583 is repeated in both directions (\c repeat).
1584
1585 Example:
1586
1587 \snippet code/doc_src_stylesheet.qdoc 38
1588
1589 \section2 background-position
1590 \table
1591 \row \li \b Type \li \l{#Alignment}{Alignment}
1592 \endtable
1593 The alignment of the background image within the \c
1594 background-origin rectangle.
1595
1596 If this property is not specified, the alignment is \c
1597 top \c left.
1598
1599 Example:
1600
1601 \snippet code/doc_src_stylesheet.qdoc 39
1602
1603 \section2 background-attachment
1604 \target background-attachment-prop
1605 \table
1606 \row \li \b Type \li \l{#Attachment}{Attachment}
1607 \endtable
1608 Determines whether the background-image in a QAbstractScrollArea
1609 is scrolled or fixed with respect to the viewport.
1610 By default, the background-image scrolls with the viewport.
1611
1612 Example:
1613
1614 \snippet code/doc_src_stylesheet.qdoc 40
1615
1616 See also \l{Qt Style Sheets Reference#background-prop}{background}
1617
1618 \section2 background-clip
1619 \target background-clip-prop
1620 \table
1621 \row \li \b Type \li \l{#Origin}{Origin}
1622 \endtable
1623 The widget's rectangle, in which the \c background is drawn.
1624
1625 This property specifies the rectangle to which the \c background-color
1626 and \c background-image are clipped.
1627
1628 This property is supported by QAbstractItemView
1629 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1630 QComboBox, QDialog, QFrame, QGroupBox, QLabel,
1631 QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip,
1632 and plain \l{QWidget}s.
1633
1634 If this property is not specified, the default is \c
1635 border.
1636
1637 Example:
1638
1639 \snippet code/doc_src_stylesheet.qdoc 41
1640
1641 See also \l{Qt Style Sheets Reference#background-prop}{background},
1642 \l{#background-origin-prop}{background-origin} and \l{The Box Model}.
1643
1644 \section2 background-origin
1645 \target background-origin-prop
1646 \table
1647 \row \li \b Type \li \l{#Origin}{Origin}
1648 \endtable
1649
1650 The widget's background rectangle, to use in conjunction
1651 with \c background-position and \c background-image.
1652
1653 This property is supported by QAbstractItemView
1654 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1655 QComboBox, QDialog, QFrame, QGroupBox, QLabel,
1656 QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip,
1657 and plain \l{QWidget}s.
1658
1659 If this property is not specified, the default is \c
1660 padding.
1661
1662 Example:
1663
1664 \snippet code/doc_src_stylesheet.qdoc 42
1665
1666 See also \l{Qt Style Sheets Reference#background-prop}{background} and
1667 \l{The Box Model}.
1668
1669 \section2 border
1670 \target border-prop
1671 \table
1672 \row \li \b Type \li \l{#Border}{Border}
1673 \endtable
1674
1675 Shorthand notation for setting the widget's border. Equivalent
1676 to specifying \c border-color, \c border-style, and/or
1677 \c border-width.
1678
1679 This property is supported by QAbstractItemView
1680 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1681 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit,
1682 QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter,
1683 QTextEdit, QToolTip, and plain \l{QWidget}s.
1684
1685 Example:
1686
1687 \snippet code/doc_src_stylesheet.qdoc 43
1688
1689 \section2 border-top
1690
1691 \table
1692 \row \li \b Type \li \l{#Border}{Border}
1693 \endtable
1694
1695 Shorthand notation for setting the widget's top border.
1696 Equivalent to specifying \c border-top-color, \c
1697 border-top-style, and/or \c border-top-width.
1698
1699 \section2 border-right
1700 \table
1701 \row \li \b Type \li \l{#Border}{Border}
1702 \endtable
1703
1704 Shorthand notation for setting the widget's right border.
1705 Equivalent to specifying \c border-right-color, \c
1706 border-right-style, and/or \c border-right-width.
1707
1708 \section2 border-bottom
1709 \table
1710 \row \li \b Type \li \l{#Border}{Border}
1711 \endtable
1712
1713 Shorthand notation for setting the widget's bottom border.
1714 Equivalent to specifying \c border-bottom-color, \c
1715 border-bottom-style, and/or \c border-bottom-width.
1716
1717 \section2 border-left
1718 \table
1719 \row \li \b Type \li \l{#Border}{Border}
1720 \endtable
1721
1722 Shorthand notation for setting the widget's left border.
1723 Equivalent to specifying \c border-left-color, \c
1724 border-left-style, and/or \c border-left-width.
1725
1726
1727 \section2 border-color
1728 \target border-attrs
1729 \target border-color-prop
1730 \table
1731 \row \li \b Type \li \l{#Box Colors}{Box Colors}
1732 \endtable
1733
1734 The color of all the border's edges. Equivalent to
1735 specifying \c border-top-color, \c border-right-color, \c
1736 border-bottom-color, and \c border-left-color.
1737
1738 This property is supported by QAbstractItemView
1739 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1740 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit,
1741 QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter,
1742 QTextEdit, QToolTip, and plain \l{QWidget}s.
1743
1744 If this property is not specified, it defaults to
1745 \l{#color-prop}{color} (i.e., the widget's foreground
1746 color).
1747
1748 Example:
1749
1750 \snippet code/doc_src_stylesheet.qdoc 44
1751
1752 See also \l{Qt Style Sheets Reference#border-style-prop}{border-style},
1753 \l{Qt Style Sheets Reference#border-width-prop}{border-width},
1754 \l{#border-image-prop}{border-image}, and \l{The Box Model}.
1755
1756 \section2 border-top-color
1757 \table
1758 \row \li \b Type \li \l{#Brush}{Brush}
1759 \endtable
1760
1761 The color of the border's top edge.
1762
1763 \section2 border-right-color
1764 \table
1765 \row \li \b Type \li \l{#Brush}{Brush}
1766 \endtable
1767
1768 The color of the border's right edge.
1769
1770 \section2 border-bottom-color
1771 \table
1772 \row \li \b Type \li \l{#Brush}{Brush}
1773 \endtable
1774
1775 The color of the border's bottom edge.
1776
1777 \section2 border-left-color
1778 \table
1779 \row \li \b Type \li \l{#Brush}{Brush}
1780 \endtable
1781
1782 The color of the border's left edge.
1783
1784 \section2 border-image
1785 \target border-image-prop
1786 \table
1787 \row \li \b Type \li \l{#Border Image}{Border Image}
1788 \endtable
1789
1790 The image used to fill the border. The image is cut into
1791 nine parts and stretched appropriately if necessary. See
1792 \l{#Border Image}{Border Image} for details.
1793
1794 This property is supported by QAbstractItemView
1795 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1796 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit,
1797 QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter,
1798 QTextEdit and QToolTip.
1799
1800 See also \l{#border-color-prop}{border-color},
1801 \l{Qt Style Sheets Reference#border-style-prop}{border-style},
1802 \l{Qt Style Sheets Reference#border-width-prop}{border-width}, and
1803 \l{The Box Model}.
1804
1805 \section2 border-radius
1806 \target border-radius-prop
1807 \table
1808 \row \li \b Type \li \l{#Radius}{Radius}
1809 \endtable
1810
1811 The radius of the border's corners. Equivalent to
1812 specifying \c border-top-left-radius, \c
1813 border-top-right-radius, \c border-bottom-right-radius,
1814 and \c border-bottom-left-radius.
1815
1816 The border-radius clips the element's
1817 \l{Qt Style Sheets Reference#background-prop}{background}.
1818
1819 This property is supported by QAbstractItemView
1820 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1821 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
1822 QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit,
1823 and QToolTip.
1824
1825 If this property is not specified, it defaults to 0.
1826
1827 Example:
1828
1829 \snippet code/doc_src_stylesheet.qdoc 45
1830
1831 See also \l{Qt Style Sheets Reference#border-width-prop}{border-width} and
1832 \l{The Box Model}.
1833
1834 \section2 border-top-left-radius
1835 \table
1836 \row \li \b Type \li \l{#Radius}{Radius}
1837 \endtable
1838
1839 The radius of the border's top-left corner.
1840
1841 \section2 border-top-right-radius
1842 \table
1843 \row \li \b Type \li \l{#Radius}{Radius}
1844 \endtable
1845
1846 The radius of the border's top-right corner.
1847
1848 \section2 border-bottom-right-radius
1849 \table
1850 \row \li \b Type \li \l{#Radius}{Radius}
1851 \endtable
1852
1853 The radius of the border's bottom-right corner. Setting
1854 this property to a positive value results in a rounded
1855 corner.
1856
1857 \section2 border-bottom-left-radius
1858 \table
1859 \row \li \b Type \li \l{#Radius}{Radius}
1860 \endtable
1861
1862 The radius of the border's bottom-left corner. Setting this
1863 property to a positive value results in a rounded corner.
1864
1865 \section2 border-style
1866 \target border-style-prop
1867 \table
1868 \row \li \b Type \li \l{#Border Style}{Border Style}
1869 \endtable
1870
1871 The style of all the border's edges.
1872
1873 This property is supported by QAbstractItemView
1874 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1875 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
1876 QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit,
1877 and QToolTip.
1878
1879 If this property is not specified, it defaults to \c none.
1880
1881 Example:
1882
1883 \snippet code/doc_src_stylesheet.qdoc 46
1884
1885 See also \l{#border-color-prop}{border-color},
1886 \l{Qt Style Sheets Reference#border-style-prop}{border-style},
1887 \l{#border-image-prop}{border-image}, and \l{The Box Model}.
1888
1889 \section2 border-top-style
1890 \table
1891 \row \li \b Type \li \l{#Border Style}{Border Style}}
1892 \endtable
1893
1894 The style of the border's top edge.
1895
1896 \section2 border-right-style
1897 \table
1898 \row \li \b Type \li \l{#Border Style}{Border Style}
1899 \endtable
1900
1901 The style of the border's right edge.
1902
1903 \section2 border-bottom-style
1904 \table
1905 \row \li \b Type \li \l{#Border Style}{Border Style}
1906 \endtable
1907
1908 The style of the border's bottom edge.
1909
1910 \section2 border-left-style
1911 \table
1912 \row \li \b Type \li \l{#Border Style}{Border Style}
1913 \endtable
1914
1915 The style of the border's left edge.
1916
1917 \section2 border-width
1918 \target border-width-prop
1919 \table
1920 \row \li \b Type \li \l{#Box Lengths}{Box Lengths}
1921 \endtable
1922
1923 The width of the border. Equivalent to setting \c
1924 border-top-width, \c border-right-width, \c
1925 border-bottom-width, and \c border-left-width.
1926
1927 This property is supported by QAbstractItemView
1928 subclasses, QAbstractSpinBox subclasses, QCheckBox,
1929 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
1930 QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit,
1931 and QToolTip.
1932
1933 Example:
1934
1935 \snippet code/doc_src_stylesheet.qdoc 47
1936
1937 See also \l{#border-color-prop}{border-color},
1938 \l{#border-radius-prop}{border-radius},
1939 \l{Qt Style Sheets Reference#border-style-prop}{border-style},
1940 \l{#border-image-prop}{border-image}, and
1941 \l{The Box Model}.
1942
1943 \section2 border-top-width
1944 \table
1945 \row \li \b Type \li \l{#Length}{Length}
1946 \endtable
1947
1948 The width of the border's top edge.
1949
1950 \section2 border-right-width
1951 \table
1952 \row \li \b Type \li \l{#Length}{Length}
1953 \endtable
1954
1955 The width of the border's right edge.
1956
1957 \section2 border-bottom-width
1958 \table
1959 \row \li \b Type \li \l{#Length}{Length}
1960 \endtable
1961
1962 The width of the border's bottom edge.
1963
1964 \section2 border-left-width
1965 \table
1966 \row \li \b Type \li \l{#Length}{Length}
1967 \endtable
1968
1969 The width of the border's left edge.
1970
1971 \section2 bottom
1972 \target bottom-prop
1973 \table
1974 \row \li \b Type \li \l{#Length}{Length}
1975 \endtable
1976
1977 If \l{#position-prop}{position} is \c relative (the
1978 default), moves a subcontrol by a certain offset up;
1979 specifying \tt{bottom: \e{y}} is then equivalent to
1980 specifying \tt{\l{Qt Style Sheets Reference#top-prop}{top}: -\e{y}}.
1981
1982 If \l{#position-prop}{position} is \c absolute, the \c
1983 bottom property specifies the subcontrol's bottom edge
1984 in relation to the parent's bottom edge (see also
1985 \l{Qt Style Sheets Reference#subcontrol-origin-prop}
1986 {subcontrol-origin}).
1987
1988 Example:
1989
1990 \snippet code/doc_src_stylesheet.qdoc 48
1991
1992 See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and
1993 \l{Qt Style Sheets Reference#top-prop}{top}.
1994
1995
1996 \section2 button-layout
1997 \target button-layout-prop
1998 \table
1999 \row \li \b Type \li \l{#Number}{Number}
2000 \endtable
2001
2002 The layout of buttons in a QDialogButtonBox or
2003 a QMessageBox. The possible values are 0
2004 (\l{QDialogButtonBox::}{WinLayout}), 1
2005 (\l{QDialogButtonBox::}{MacLayout}), 2
2006 (\l{QDialogButtonBox::}{KdeLayout}), 3
2007 (\l{QDialogButtonBox::}{GnomeLayout}) and 5
2008 (\l{QDialogButtonBox::}{AndroidLayout}).
2009
2010 If this property is not specified, it defaults to the
2011 value specified by the current style for the
2012 \l{QStyle::}{SH_DialogButtonLayout} style hint.
2013
2014 Example:
2015
2016 \snippet code/doc_src_stylesheet.qdoc 49
2017
2018
2019 \section2 color
2020 \target color-prop
2021 \table
2022 \row \li \b Type \li \l{#Brush}{Brush} \br
2023 \endtable
2024
2025 The color used to render text.
2026
2027 This property is supported by all widgets that respect
2028 the \l QWidget::palette.
2029
2030 If this property is not set, the default is whatever is
2031 set for in the widget's palette for the
2032 QWidget::foregroundRole (typically black).
2033
2034 Example:
2035
2036 \snippet code/doc_src_stylesheet.qdoc 50
2037
2038 See also \l{Qt Style Sheets Reference#background-prop}{background} and
2039 \l{#selection-color-prop}{selection-color}.
2040
2041 \section2 dialogbuttonbox-buttons-have-icons
2042 \table
2043 \row \li \b Type \li \l{#Boolean}{Boolean}
2044 \endtable
2045
2046 Whether the buttons in a QDialogButtonBox show icons
2047
2048 If this property is set to 1, the buttons of a QDialogButtonBox
2049 show icons; if it is set to 0, the icons are not shown.
2050
2051 See the \l{Qt Style Sheets Reference#list of icons}{List of Icons}
2052 section for information on how to set icons.
2053
2054 \snippet code/doc_src_stylesheet.qdoc 51
2055
2056 \note Styles defining this property must be applied before the
2057 QDialogButtonBox is created; this means that you must apply the
2058 style to the parent widget or to the application itself.
2059
2060 \omit
2061 \row
2062 \li \b{\c etch-disabled-text}*
2063 \li \l{#Boolean}{Boolean}
2064 \li Whether disabled text is drawn etched.
2065
2066 If this property is not specified, it defaults to the
2067 value specified by the current style for the
2068 \l{QStyle::}{SH_EtchDisabledText} style hint.
2069
2070 Example:
2071
2072 \snippet code/doc_src_stylesheet.qdoc 52
2073 \endomit
2074
2075 \section2 font
2076 \target font-prop
2077 \table
2078 \row \li \b Type \li \l{#Font}{Font}
2079 \endtable
2080
2081 Shorthand notation for setting the text's font. Equivalent
2082 to specifying \c font-family, \c font-size, \c font-style,
2083 and/or \c font-weight.
2084
2085 This property is supported by all widgets that respect
2086 the \l QWidget::font.
2087
2088 If this property is not set, the default is the
2089 QWidget::font.
2090
2091 Example:
2092
2093 \snippet code/doc_src_stylesheet.qdoc 53
2094
2095 \section2 font-family
2096 \table
2097 \row \li \b Type \li String
2098 \endtable
2099
2100 The font family.
2101
2102 Example:
2103
2104 \snippet code/doc_src_stylesheet.qdoc 54
2105
2106 \section2 font-size
2107 \table
2108 \row \li \b Type \li \l{#Font Size}{Font Size}
2109 \endtable
2110
2111 The font size. In this version of Qt, only pt and px metrics are
2112 supported.
2113
2114 Example:
2115
2116 \snippet code/doc_src_stylesheet.qdoc 55
2117
2118 \section2 font-style
2119 \table
2120 \row \li \b Type \li \l {#Font Style} {Font Style}
2121 \endtable
2122
2123 The font style.
2124
2125 Example:
2126
2127 \snippet code/doc_src_stylesheet.qdoc 56
2128
2129 \section2 font-weight
2130 \table
2131 \row \li \b Type \li \l{#Font Weight}{Font Weight}
2132 \endtable
2133
2134 The weight of the font.
2135
2136 \section2 gridline-color*
2137 \target gridline-color-prop
2138 \table
2139 \row \li \b Type \li \l{#Color}{Color}
2140 \endtable
2141
2142 The color of the grid line in a QTableView.
2143
2144 If this property is not specified, it defaults to the
2145 value specified by the current style for the
2146 \l{QStyle::}{SH_Table_GridLineColor} style hint.
2147
2148 Example:
2149
2150 \snippet code/doc_src_stylesheet.qdoc 57
2151
2152
2153 \section2 height
2154 \target height-prop
2155 \table
2156 \row \li \b Type \li \l{#Length}{Length}
2157 \endtable
2158
2159 The height of a subcontrol (or in some case, a widget).
2160
2161 If this property is not specified, it defaults to a value
2162 that depends on the subcontrol/widget and on the current style.
2163
2164 \warning Unless otherwise specified, this property has no effect
2165 when set on widgets. If you want a widget with a fixed height, set
2166 the \l{#min-width-prop}{min-height} and
2167 \l{#max-width-prop}{max-height} to the same value.
2168
2169 Example:
2170
2171 \snippet code/doc_src_stylesheet.qdoc 58
2172
2173 See also \l{#width-prop}{width}.
2174
2175 \section2 icon
2176 \target icon-prop
2177 \table
2178 \row \li \b Type \li \l{#Url}{Url}+
2179 \endtable
2180
2181 The icon that is used, for widgets that have an icon.
2182
2183 The only widget currently supporting this property is QPushButton.
2184
2185 \note It's the application's responsibility to assign an icon to a
2186 button (using the QAbstractButton API), and not the style's. So be
2187 careful setting it unless your stylesheet is targeting a specific
2188 application.
2189
2190 Available since 5.15.
2191
2192 \section2 icon-size
2193 \target icon-size-prop
2194 \table
2195 \row \li \b Type \li \l{#Length}{Length}
2196 \endtable
2197
2198 The width and height of the icon in a widget.
2199
2200 The icon size of the following widgets can be set using this
2201 property.
2202 \list
2203 \li QCheckBox
2204 \li QListView
2205 \li QPushButton
2206 \li QRadioButton
2207 \li QTabBar
2208 \li QToolBar
2209 \li QToolBox
2210 \li QTreeView
2211 \endlist
2212
2213 \section2 image*
2214 \target image-prop
2215 \table
2216 \row \li \b Type \li \l{#Url}{Url}+
2217 \endtable
2218
2219 The image that is drawn in the contents rectangle of a
2220 subcontrol.
2221
2222 The image property accepts a list of \l{#Url}{Url}s or
2223 an \c{svg}. The actual image that is drawn is determined
2224 using the same algorithm as QIcon (i.e) the image is never scaled
2225 up but always scaled down if necessary. If a \c{svg} is specified,
2226 the image is scaled to the size of the contents rectangle.
2227
2228 Setting the image property on sub controls implicitly sets the
2229 width and height of the sub-control (unless the image in a SVG).
2230
2231 In Qt 4.3 and later, the alignment of the
2232 image within the rectangle can be specified using
2233 \l{image-position-prop}{image-position}.
2234
2235 This property is for subcontrols only--we don't support it for
2236 other elements.
2237
2238 \warning The QIcon SVG plugin is needed to render SVG images.
2239
2240 Example:
2241
2242 \snippet code/doc_src_stylesheet.qdoc 59
2243
2244
2245 \section2 image-position
2246 \target image-position-prop
2247 \table
2248 \row \li \b Type \li \l{#Alignment}{alignment}
2249 \endtable
2250
2251 In Qt 4.3 and later, the alignment of the image image's position can be specified
2252 using relative or absolute position.
2253
2254 \section2 left
2255 \target left-prop
2256 \table
2257 \row \li \b Type \li \l{#Length}{Length}
2258 \endtable
2259
2260 If \l{#position-prop}{position} is \c relative (the
2261 default), moves a subcontrol by a certain offset to
2262 the right.
2263
2264 If \l{#position-prop}{position} is \c absolute, the \c
2265 left property specifies the subcontrol's left edge in
2266 relation to the parent's left edge (see also
2267 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}).
2268
2269 If this property is not specified, it defaults to \c 0.
2270
2271 Example:
2272
2273 \snippet code/doc_src_stylesheet.qdoc 60
2274
2275 See also \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and
2276 \l{#bottom-prop}{bottom}.
2277
2278 \section2 letter-spacing
2279 \table
2280 \row \li \b Type \li \l{#Length}{Length}
2281 \endtable
2282
2283 Space between characters in a string within a widget.
2284
2285 \section2 lineedit-password-character*
2286 \target lineedit-password-character-prop
2287 \table
2288 \row \li \b Type \li \l{#Number}{Number}
2289 \endtable
2290
2291 The QLineEdit password character as a Unicode number.
2292
2293 If this property is not specified, it defaults to the
2294 value specified by the current style for the
2295 \l{QStyle::}{SH_LineEdit_PasswordCharacter} style hint.
2296
2297 Example:
2298
2299 \snippet code/doc_src_stylesheet.qdoc 61
2300
2301
2302 \section2 lineedit-password-mask-delay*
2303 \target lineedit-password-mask-delay-prop
2304 \table
2305 \row \li \b Type \li \l{#Number}{Number}
2306 \endtable
2307
2308 The QLineEdit password mask delay in milliseconds before
2309 \l{#lineedit-password-character-prop}{lineedit-password-character} is applied to visible character.
2310
2311 If this property is not specified, it defaults to the
2312 value specified by the current style for the
2313 \l{QStyle::}{SH_LineEdit_PasswordMaskDelay} style hint.
2314
2315 Available since Qt 5.4.
2316
2317 Example:
2318
2319 \snippet code/doc_src_stylesheet.qdoc 160
2320
2321 \section2 margin
2322 \target margin-prop
2323 \table
2324 \row \li \b Type \li \l {#Box Lengths}{Box Lengths}
2325 \endtable
2326
2327 The widget's margins. Equivalent to specifying \c
2328 margin-top, \c margin-right, \c margin-bottom, and \c
2329 margin-left.
2330
2331 This property is supported by QAbstractItemView
2332 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2333 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2334 QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit,
2335 and QToolTip.
2336
2337 If this property is not specified, it defaults to \c 0.
2338
2339 Example:
2340
2341 \snippet code/doc_src_stylesheet.qdoc 62
2342
2343 See also \l{Qt Style Sheets Reference#padding-prop}{padding},
2344 \l{#spacing-prop}{spacing}, and \l{The Box Model}.
2345
2346 \section2 margin-top
2347 \table
2348 \row \li \b Type \li \l{#Length}{Length}
2349 \endtable
2350 The widget's top margin.
2351
2352 \section2 margin-right
2353 \table
2354 \row \li \b Type \li \l{#Length}{Length}
2355 \endtable
2356 The widget's right margin.
2357
2358 \section2 margin-bottom
2359 \table
2360 \row \li \b Type \li \l{#Length}{Length}
2361 \endtable
2362 The widget's bottom margin.
2363
2364 \section2 margin-left
2365 \table
2366 \row \li \b Type \li \l{#Length}{Length}
2367 \endtable
2368 The widget's left margin.
2369
2370 \section2 max-height
2371 \target max-height-prop
2372 \table
2373 \row \li \b Type \li \l{#Length}{Length}
2374 \endtable
2375
2376 The widget's or a subcontrol's maximum height.
2377
2378 This property is supported by QAbstractItemView
2379 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2380 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2381 QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox,
2382 QSplitter, QStatusBar, QTextEdit, and QToolTip.
2383
2384 The value is relative to the contents rect in the \l{The
2385 Box Model}{box model}.
2386
2387 Example:
2388
2389 \snippet code/doc_src_stylesheet.qdoc 63
2390
2391 See also \l{#max-width-prop}{max-width}.
2392
2393 \section2 max-width
2394 \target max-width-prop
2395 \table
2396 \row \li \b Type \li \l{#Length}{Length}
2397 \endtable
2398
2399 The widget's or a subcontrol's maximum width.
2400
2401 This property is supported by QAbstractItemView
2402 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2403 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2404 QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox,
2405 QSplitter, QStatusBar, QTextEdit, and QToolTip.
2406
2407 The value is relative to the contents rect in the \l{The
2408 Box Model}{box model}.
2409
2410 Example:
2411
2412 \snippet code/doc_src_stylesheet.qdoc 64
2413
2414 See also \l{#max-height-prop}{max-height}.
2415
2416 \section2 messagebox-text-interaction-flags*
2417 \target messagebox-text-interaction-flags-prop
2418 \table
2419 \row \li \b Type \li \l{#Number}{Number}
2420 \endtable
2421
2422 The interaction behavior for text in a message box.
2423 Possible values are based on Qt::TextInteractionFlags.
2424
2425 If this property is not specified, it defaults to the
2426 value specified by the current style for the
2427 \l{QStyle::}{SH_MessageBox_TextInteractionFlags} style
2428 hint.
2429
2430 Example:
2431
2432 \snippet code/doc_src_stylesheet.qdoc 65
2433
2434 \section2 min-height
2435 \target min-height-prop
2436 \table
2437 \row \li \b Type \li \l{#Length}{Length}
2438 \endtable
2439
2440 The widget's or a subcontrol's minimum height.
2441
2442 This property is supported by QAbstractItemView
2443 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2444 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2445 QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox,
2446 QSplitter, QStatusBar, QTextEdit, QToolButton, and QToolTip.
2447
2448 If this property is not specified, the minimum height is
2449 derived based on the widget's contents and the style.
2450
2451 The value is relative to the contents rect in the \l{The
2452 Box Model}{box model}.
2453
2454 Example:
2455
2456 \snippet code/doc_src_stylesheet.qdoc 66
2457
2458 \note Setting this property might allow widgets to shrink
2459 smaller than the space required for the contents.
2460
2461 See also \l{#min-width-prop}{min-width}.
2462
2463 \section2 min-width
2464 \target min-width-prop
2465 \table
2466 \row \li \b Type \li \l{#Length}{Length}
2467 \endtable
2468
2469 The widget's or a subcontrol's minimum width.
2470
2471 This property is supported by QAbstractItemView
2472 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2473 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2474 QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox,
2475 QSplitter, QStatusBar, QTextEdit, QToolButton, and QToolTip.
2476
2477 If this property is not specified, the minimum width is
2478 derived based on the widget's contents and the style.
2479
2480 The value is relative to the contents rect in the \l{The
2481 Box Model}{box model}.
2482
2483 Example:
2484
2485 \snippet code/doc_src_stylesheet.qdoc 67
2486
2487 \note Setting this property might allow widgets to shrink
2488 smaller than the space required for the contents.
2489
2490 See also \l{#min-height-prop}{min-height}.
2491
2492 \section2 opacity*
2493 \target opacity-prop
2494 \table
2495 \row \li \b Type \li \l{#Number}{Number}
2496 \endtable
2497
2498 The opacity for a widget. Possible values are from 0
2499 (transparent) to 255 (opaque). For the moment, this is
2500 only supported for \l{QToolTip}{tooltips}.
2501
2502 If this property is not specified, it defaults to the
2503 value specified by the current style for the
2504 \l{QStyle::}{SH_ToolTipLabel_Opacity} style hint.
2505
2506 Example:
2507
2508 \snippet code/doc_src_stylesheet.qdoc 68
2509
2510 \section2 outline
2511
2512 The outline drawn around the object's border.
2513
2514 \section2 outline-color
2515 \table
2516 \row \li \b Type \li \l{#Color}{Color}
2517 \endtable
2518
2519 The color of the outline.
2520 See also \l{Qt Style Sheets Reference#border-color-prop}{border-color}
2521
2522 \section2 outline-offset
2523 \table
2524 \row \li \b Type \li \l{#Length}{Length}
2525 \endtable
2526
2527 The outline's offset from the border of the widget.
2528
2529 \section2 outline-style
2530
2531 Specifies the pattern used to draw the outline.
2532 See also \l{Qt Style Sheets Reference#border-style-prop}{border-style}
2533
2534 \section2 outline-radius
2535
2536 Adds rounded corners to the outline.
2537
2538 \section2 outline-bottom-left-radius
2539 \table
2540 \row \li \b Type \li \l{#Radius}{Radius}
2541 \endtable
2542
2543 The radius for the bottom-left rounded corner of the outline.
2544
2545 \section2 outline-bottom-right-radius
2546 \table
2547 \row \li \b Type \li \l{#Radius}{Radius}
2548 \endtable
2549
2550 The radius for the bottom-right rounded corner of the outline.
2551
2552 \section2 outline-top-left-radius
2553 \table
2554 \row \li \b Type \li \l{#Radius}{Radius}
2555 \endtable
2556
2557 The radius for the top-left corner of the outline.
2558
2559 \section2 outline-top-right-radius
2560 \table
2561 \row \li \b Type \li \l{#Radius}{Radius}
2562 \endtable
2563
2564 The radius for the top-right rounded corner of the outline.
2565
2566 \section2 padding
2567 \target padding-prop
2568 \table
2569 \row \li \b Type \li \l{#Box Lengths}{Box Lengths}
2570 \endtable
2571
2572 The widget's padding. Equivalent to specifying \c
2573 padding-top, \c padding-right, \c padding-bottom, and \c
2574 padding-left.
2575
2576 This property is supported by QAbstractItemView
2577 subclasses, QAbstractSpinBox subclasses, QCheckBox,
2578 QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu,
2579 QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit,
2580 and QToolTip.
2581
2582 If this property is not specified, it defaults to \c 0.
2583
2584 Example:
2585
2586 \snippet code/doc_src_stylesheet.qdoc 69
2587
2588 See also \l{#margin-prop}{margin},
2589 \l{#spacing-prop}{spacing}, and \l{The Box Model}.
2590
2591 \section2 padding-top
2592 \table
2593 \row \li \b Type \li \l{#Length}{Length}
2594 \endtable
2595
2596 The widget's top padding.
2597
2598 \section2 padding-right
2599 \table
2600 \row \li \b Type \li \l{#Length}{Length}
2601 \endtable
2602
2603 The widget's right padding.
2604
2605 \section2 padding-bottom
2606 \table
2607 \row \li \b Type \li \l{#Length}{Length}
2608 \endtable
2609
2610 The widget's bottom padding.
2611
2612 \section2 padding-left
2613 \table
2614 \row \li \b Type \li \l{#Length}{Length}
2615 \endtable
2616
2617 The widget's left padding.
2618
2619 \section2 paint-alternating-row-colors-for-empty-area
2620 \target paint-alternating-row-colors-for-empty-area-prop
2621 \table
2622 \row \li \b Type \li \c bool
2623 \endtable
2624
2625 Whether the QTreeView paints alternating row colors for the empty
2626 area (i.e the area where there are no items)
2627
2628 \section2 placeholder-text-color*
2629 \target placeholder-text-color-prop
2630 \table
2631 \row \li \b Type \li \l{#Brush}{Brush} \br
2632 \endtable
2633
2634 The color used for the placeholder text of text editing widgets.
2635
2636 If this property is not set, the default value is whatever
2637 is set for the palette's \l{QPalette::}{PlaceholderText}
2638 role.
2639
2640 Example:
2641
2642 \snippet code/doc_src_stylesheet.qdoc 163
2643
2644 Available since 6.5.
2645
2646 \section2 position
2647 \target position-prop
2648 \table
2649 \row \li \b Type \li \c relative \br
2650 | \c absolute
2651 \endtable
2652
2653 Whether offsets specified using \l{Qt Style Sheets Reference#left-prop}{left},
2654 \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and
2655 \l{#bottom-prop}{bottom} are relative or absolute
2656 coordinates.
2657
2658 If this property is not specified, it defaults to \c
2659 relative.
2660
2661 \section2 right
2662 \target right-prop
2663 \table
2664 \row \li \b Type \li \l{#Length}{Length}
2665 \endtable
2666
2667 If \l{#position-prop}{position} is \c relative (the
2668 default), moves a subcontrol by a certain offset to
2669 the left; specifying \tt{right: \e{x}} is then equivalent
2670 to specifying \tt{\l{Qt Style Sheets Reference#left-prop}{left}: -\e{x}}.
2671
2672 If \l{#position-prop}{position} is \c absolute, the \c
2673 right property specifies the subcontrol's right edge in
2674 relation to the parent's right edge (see also
2675 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}).
2676
2677 Example:
2678
2679 \snippet code/doc_src_stylesheet.qdoc 70
2680
2681 See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{Qt Style Sheets Reference#top-prop}{top}, and
2682 \l{#bottom-prop}{bottom}.
2683
2684 \section2 selection-background-color*
2685 \target selection-background-color-prop
2686 \table
2687 \row \li \b Type \li \l{#Brush}{Brush}
2688 \endtable
2689
2690 The background of selected text or items.
2691
2692 This property is supported by all widgets that respect
2693 the \l QWidget::palette and that show selection text.
2694
2695 If this property is not set, the default value is
2696 whatever is set for the palette's
2697 \l{QPalette::}{Highlight} role.
2698
2699 Example:
2700
2701 \snippet code/doc_src_stylesheet.qdoc 71
2702
2703 See also \l{#selection-color-prop}{selection-color} and
2704 \l{Qt Style Sheets Reference#background-prop}{background}.
2705
2706
2707 \section2 selection-color*
2708 \target selection-color-prop
2709 \table
2710 \row \li \b Type \li \l{#Brush}{Brush} \br
2711 \endtable
2712
2713 The foreground of selected text or items.
2714
2715 This property is supported by all widgets that respect
2716 the \l QWidget::palette and that show selection text.
2717
2718 If this property is not set, the default value is
2719 whatever is set for the palette's
2720 \l{QPalette::}{HighlightedText} role.
2721
2722 Example:
2723
2724 \snippet code/doc_src_stylesheet.qdoc 72
2725
2726 See also
2727 \l{#selection-background-color-prop}{selection-background-color}
2728 and \l{#color-prop}{color}.
2729
2730
2731 \section2 show-decoration-selected*
2732 \target show-decoration-selected-prop
2733 \table
2734 \row \li \b Type \li \l{#Boolean}{Boolean}
2735 \endtable
2736
2737 Controls whether selections in a QListView cover the
2738 entire row or just the extent of the text.
2739
2740 If this property is not specified, it defaults to the
2741 value specified by the current style for the
2742 \l{QStyle::}{SH_ItemView_ShowDecorationSelected} style
2743 hint.
2744
2745 Example:
2746
2747 \snippet code/doc_src_stylesheet.qdoc 73
2748
2749 \section2 spacing*
2750 \target spacing-prop
2751 \table
2752 \row \li \b Type \li \l{#Length}{Length}
2753 \endtable
2754
2755 Internal spacing in the widget.
2756
2757 This property is supported by QCheckBox, checkable
2758 \l{QGroupBox}es, QMenuBar, and QRadioButton.
2759
2760 If this property is not specified, the default value
2761 depends on the widget and on the current style.
2762
2763 Example:
2764
2765 \snippet code/doc_src_stylesheet.qdoc 74
2766
2767 See also \l{Qt Style Sheets Reference#padding-prop}{padding} and
2768 \l{#margin-prop}{margin}.
2769
2770
2771 \section2 subcontrol-origin*
2772 \target subcontrol-origin-prop
2773 \table
2774 \row \li \b Type \li \l{#Origin}{Origin}
2775 \endtable
2776
2777 The origin rectangle of the subcontrol within the
2778 parent element.
2779
2780 If this property is not specified, the default is \c
2781 padding.
2782
2783 Example:
2784
2785 \snippet code/doc_src_stylesheet.qdoc 75
2786
2787 See also
2788 \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position}.
2789
2790 \section2 subcontrol-position*
2791 \target subcontrol-position-prop
2792 \table
2793 \row \li \b Type \li \l{#Alignment}{Alignment}
2794 \endtable
2795
2796 The alignment of the subcontrol within the origin
2797 rectangle specified by \l{Qt Style Sheets Reference#subcontrol-origin-prop}
2798 {subcontrol-origin}.
2799
2800 If this property is not specified, it defaults to a value
2801 that depends on the subcontrol.
2802
2803 Example:
2804
2805 \snippet code/doc_src_stylesheet.qdoc 76
2806
2807 See also
2808 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}.
2809
2810 \section2 titlebar-show-tooltips-on-buttons
2811 \target titlebar-show-tooltips-on-buttons-prop
2812 \table
2813 \row \li \b Type \li \c bool
2814 \endtable
2815
2816 Whether tool tips are shown on window title bar buttons.
2817
2818
2819 \section2 widget-animation-duration*
2820 \target widget-animation-duration
2821 \table
2822 \row \li \b Type \li \l{#Number}{Number}
2823 \endtable
2824
2825 How much an animation should last (in milliseconds).
2826 A value equal to zero means that the animations will be disabled.
2827
2828 If this property is not specified, it defaults to the
2829 value specified by the current style for the
2830 \l{QStyle::}{SH_Widget_Animation_Duration} style hint.
2831
2832 Available since Qt 5.10.
2833
2834 Example:
2835
2836 \snippet code/doc_src_stylesheet.qdoc 162
2837
2838 \section2 text-align
2839 \target text-align-prop
2840 \table
2841 \row \li \b Type \li \l{#Alignment}{Alignment}
2842 \endtable
2843
2844 The alignment of text and icon within the contents of the widget.
2845
2846 If this value is not specified, it defaults to the value
2847 that depends on the native style.
2848
2849 Example:
2850
2851 \snippet code/doc_src_stylesheet.qdoc 77
2852
2853 This property is currently supported only by QPushButton
2854 and QProgressBar.
2855
2856 \section2 text-decoration
2857 \table
2858 \row \li \b Type
2859 \li \c none \br
2860 \c underline \br
2861 \c overline \br
2862 \c line-through
2863 \endtable
2864
2865 Additional text effects.
2866
2867
2868 \section2 top
2869 \target top-prop
2870 \table
2871 \row \li \b Type \li \l{#Length}{Length}
2872 \endtable
2873
2874 If \l{#position-prop}{position} is \c relative (the
2875 default), moves a subcontrol by a certain offset
2876 down.
2877
2878 If \l{#position-prop}{position} is \c absolute, the \c top
2879 property specifies the subcontrol's top edge in relation
2880 to the parent's top edge (see also
2881 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}).
2882
2883 If this property is not specified, it defaults to \c 0.
2884
2885 Example:
2886
2887 \snippet code/doc_src_stylesheet.qdoc 78
2888
2889 See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and
2890 \l{#bottom-prop}{bottom}.
2891
2892 \section2 width
2893 \target width-prop
2894 \table
2895 \row \li \b Type \li \l{#Length}{Length}
2896 \endtable
2897
2898 The width of a subcontrol (or a widget in some cases).
2899
2900 If this property is not specified, it defaults to a value
2901 that depends on the subcontrol/widget and on the current style.
2902
2903 \warning Unless otherwise specified, this property has no effect
2904 when set on widgets. If you want a widget with a fixed width, set
2905 the \l{#min-width-prop}{min-width} and
2906 \l{#max-width-prop}{max-width} to the same value.
2907
2908 Example:
2909
2910 \snippet code/doc_src_stylesheet.qdoc 79
2911
2912 See also \l{#height-prop}{height}.
2913
2914 \section2 word-spacing
2915 \table
2916 \row \li \b Type \li \l{#Length}{Length}
2917 \endtable
2918
2919 Space between each word in a string within a widget.
2920
2921 \section2 -qt-background-role
2922 \table
2923 \row \li \b Type \li \l{#paletterole}{PaletteRole}
2924 \endtable
2925
2926 The \c{background-color} for the subcontrol or widget based on the
2927 chosen role.
2928
2929 \section2 -qt-style-features
2930 \table
2931 \row \li \b Type \li \c list
2932 \endtable
2933
2934 The list of CSS properties that you want to apply Qt-specific styles on.
2935
2936 \note The \c list can only include properties that are not pixmap-based.
2937
2938 \target list of icons
2939 \section1 List of Icons
2940
2941 Icons used in Qt can be customized using the following properties. Each of
2942 the properties listed in this section have the type \l{#Icon}{Icon}.
2943
2944 Note that for icons to appear in buttons in a QDialogButtonBox, you need to
2945 set the dialogbuttonbox-buttons-have-icons property to true. Also, to
2946 customize the size of the icons, use the icon-size property.
2947
2948 \table 100%
2949 \header
2950 \li Name
2951 \li QStyle::StandardPixmap
2952
2953 \row
2954 \li backward-icon
2955 \li QStyle::SP_ArrowBack
2956
2957 \row
2958 \li cd-icon
2959 \li QStyle::SP_DriveCDIcon
2960
2961 \row
2962 \li computer-icon
2963 \li QStyle::SP_ComputerIcon
2964
2965 \row
2966 \li desktop-icon
2967 \li QStyle::SP_DesktopIcon
2968
2969 \row
2970 \li dialog-apply-icon
2971 \li QStyle::SP_DialogApplyButton
2972
2973 \row
2974 \li dialog-cancel-icon
2975 \li QStyle::SP_DialogCancelButton
2976
2977 \row
2978 \li dialog-close-icon
2979 \li QStyle::SP_DialogCloseButton
2980
2981 \row
2982 \li dialog-discard-icon
2983 \li QStyle::SP_DialogDiscardButton
2984
2985 \row
2986 \li dialog-help-icon
2987 \li QStyle::SP_DialogHelpButton
2988
2989 \row
2990 \li dialog-no-icon
2991 \li QStyle::SP_DialogNoButton
2992
2993 \row
2994 \li dialog-ok-icon
2995 \li QStyle::SP_DialogOkButton
2996
2997 \row
2998 \li dialog-open-icon
2999 \li QStyle::SP_DialogOpenButton
3000
3001 \row
3002 \li dialog-reset-icon
3003 \li QStyle::SP_DialogResetButton
3004
3005 \row
3006 \li dialog-save-icon
3007 \li QStyle::SP_DialogSaveButton
3008
3009 \row
3010 \li dialog-yes-icon
3011 \li QStyle::SP_DialogYesButton
3012
3013 \row
3014 \li directory-closed-icon
3015 \li QStyle::SP_DirClosedIcon
3016
3017 \row
3018 \li directory-icon
3019 \li QStyle::SP_DirIcon
3020
3021 \row
3022 \li directory-link-icon
3023 \li QStyle::SP_DirLinkIcon
3024
3025 \row
3026 \li directory-open-icon
3027 \li QStyle::SP_DirOpenIcon
3028
3029 \row
3030 \li dockwidget-close-icon
3031 \li QStyle::SP_DockWidgetCloseButton
3032
3033 \row
3034 \li downarrow-icon
3035 \li QStyle::SP_ArrowDown
3036
3037 \row
3038 \li dvd-icon
3039 \li QStyle::SP_DriveDVDIcon
3040
3041 \row
3042 \li file-icon
3043 \li QStyle::SP_FileIcon
3044
3045 \row
3046 \li file-link-icon
3047 \li QStyle::SP_FileLinkIcon
3048
3049 \omit
3050 \row
3051 \li filedialog-backward-icon
3052 \li QStyle::SP_FileDialogBack
3053 \endomit
3054
3055 \row
3056 \li filedialog-contentsview-icon
3057 \li QStyle::SP_FileDialogContentsView
3058
3059 \row
3060 \li filedialog-detailedview-icon
3061 \li QStyle::SP_FileDialogDetailedView
3062
3063 \row
3064 \li filedialog-end-icon
3065 \li QStyle::SP_FileDialogEnd
3066
3067 \row
3068 \li filedialog-infoview-icon
3069 \li QStyle::SP_FileDialogInfoView
3070
3071 \row
3072 \li filedialog-listview-icon
3073 \li QStyle::SP_FileDialogListView
3074
3075 \row
3076 \li filedialog-new-directory-icon
3077 \li QStyle::SP_FileDialogNewFolder
3078
3079 \row
3080 \li filedialog-parent-directory-icon
3081 \li QStyle::SP_FileDialogToParent
3082
3083 \row
3084 \li filedialog-start-icon
3085 \li QStyle::SP_FileDialogStart
3086
3087 \row
3088 \li floppy-icon
3089 \li QStyle::SP_DriveFDIcon
3090
3091 \row
3092 \li forward-icon
3093 \li QStyle::SP_ArrowForward
3094
3095 \row
3096 \li harddisk-icon
3097 \li QStyle::SP_DriveHDIcon
3098
3099 \row
3100 \li home-icon
3101 \li QStyle::SP_DirHomeIcon
3102
3103 \row
3104 \li lineedit-clear-button-icon
3105 \li QStyle::SP_LineEditClearButton
3106
3107 \row
3108 \li leftarrow-icon
3109 \li QStyle::SP_ArrowLeft
3110
3111 \row
3112 \li messagebox-critical-icon
3113 \li QStyle::SP_MessageBoxCritical
3114
3115 \row
3116 \li messagebox-information-icon
3117 \li QStyle::SP_MessageBoxInformation
3118
3119 \row
3120 \li messagebox-question-icon
3121 \li QStyle::SP_MessageBoxQuestion
3122
3123 \row
3124 \li messagebox-warning-icon
3125 \li QStyle::SP_MessageBoxWarning
3126
3127 \row
3128 \li network-icon
3129 \li QStyle::SP_DriveNetIcon
3130
3131 \row
3132 \li rightarrow-icon
3133 \li QStyle::SP_ArrowRight
3134
3135 \row
3136 \li titlebar-contexthelp-icon
3137 \li QStyle::SP_TitleBarContextHelpButton
3138
3139 \row
3140 \li titlebar-maximize-icon
3141 \li QStyle::SP_TitleBarMaxButton
3142
3143 \row
3144 \li titlebar-menu-icon
3145 \li QStyle::SP_TitleBarMenuButton
3146
3147 \row
3148 \li titlebar-minimize-icon
3149 \li QStyle::SP_TitleBarMinButton
3150
3151 \row
3152 \li titlebar-normal-icon
3153 \li QStyle::SP_TitleBarNormalButton
3154
3155 \row
3156 \li titlebar-shade-icon
3157 \li QStyle::SP_TitleBarShadeButton
3158
3159 \row
3160 \li titlebar-unshade-icon
3161 \li QStyle::SP_TitleBarUnshadeButton
3162
3163 \row
3164 \li trash-icon
3165 \li QStyle::SP_TrashIcon
3166
3167 \row
3168 \li uparrow-icon
3169 \li QStyle::SP_ArrowUp
3170
3171 \endtable
3172
3173 \section1 List of Property Types
3174
3175 The following table summarizes the syntax and meaning of the
3176 different property types.
3177
3178 \table 100%
3179 \header
3180 \li Type
3181 \li Syntax
3182 \li Description
3183
3184 \row
3185 \li \b Alignment \target Alignment
3186 \li \{ \c top \br
3187 | \c bottom \br
3188 | \c left \br
3189 | \c right \br
3190 | \c center \}*
3191 \li Horizontal and/or vertical alignment.
3192
3193 Example:
3194
3195 \snippet code/doc_src_stylesheet.qdoc 80
3196
3197 \row
3198 \li \b Attachment \target Attachment
3199 \li \{ \c scroll \br
3200 | \c fixed \}*
3201 \li Scroll or fixed attachment.
3202
3203 \row
3204 \li \b Background \target Background
3205 \li \{ \l{#Brush}{Brush} \br
3206 | \l{#Url}{Url} \br
3207 | \l{#Repeat}{Repeat} \br
3208 | \l{#Alignment}{Alignment} \}*
3209 \li A sequence of \l{#Brush}{Brush}, \l{#Url}{Url},
3210 \l{#Repeat}{Repeat}, and \l{#Alignment}{Alignment}.
3211
3212 \row
3213 \li \b Boolean \target Boolean
3214 \li 0 | 1
3215 \li True (\c 1) or false (\c 0).
3216
3217 Example:
3218
3219 \snippet code/doc_src_stylesheet.qdoc 81
3220
3221 \row
3222 \li \b Border \target Border
3223 \li \{ \l{#Border Style}{Border Style} \br
3224 | \l{#Length}{Length} \br
3225 | \l{#Brush}{Brush} \}*
3226 \li Shorthand border property.
3227
3228 \row
3229 \li \b{Border Image} \target Border Image
3230 \li \c none \br
3231 | \l{Url} \l{Number}\{4\} \br (\c stretch | \c repeat){0,2}
3232 \li A border image is an image that is composed of nine parts
3233 (top left, top center, top right, center left, center,
3234 center right, bottom left, bottom center, and bottom
3235 right). When a border of a certain size is required, the
3236 corner parts are used as is, and the top, right, bottom,
3237 and left parts are stretched or repeated to produce a
3238 border with the desired size.
3239
3240 See the
3241 \l{http://www.w3.org/TR/css3-background/#the-border-image}
3242 {CSS3 Draft Specification} for details.
3243
3244 \row
3245 \li \b{Border Style} \target Border Style
3246 \li \c dashed \br
3247 | \c dot-dash \br
3248 | \c dot-dot-dash \br
3249 | \c dotted \br
3250 | \c double \br
3251 | \c groove \br
3252 | \c inset \br
3253 | \c outset \br
3254 | \c ridge \br
3255 | \c solid \br
3256 | \c none
3257 \li Specifies the pattern used to draw a border.
3258 See the \l{http://www.w3.org/TR/css3-background/#border-style}
3259 {CSS3 Draft Specification} for details.
3260
3261 \row
3262 \li \b{Box Colors} \target Box Colors
3263 \li \l{#Brush}{Brush}\{1,4\}
3264 \li One to four occurrences of \l{#Brush}{Brush}, specifying the top,
3265 right, bottom, and left edges of a box, respectively. If
3266 the left color is not specified, it is taken to be the
3267 same as the right color. If the bottom color is not
3268 specified, it is taken to be the same as the top color. If
3269 the right color is not specified, it is taken to be the
3270 same as the top color.
3271
3272 Example:
3273
3274 \snippet code/doc_src_stylesheet.qdoc 82
3275
3276 \row
3277 \li \b{Box Lengths} \target Box Lengths
3278 \li \l{#Length}{Length}\{1,4\}
3279 \li One to four occurrences of \l{#Length}{Length}, specifying the
3280 top, right, bottom, and left edges of a box,
3281 respectively. If the left length is not specified, it is
3282 taken to be the same as the right length. If the bottom
3283 length is not specified, is it taken to be the same as the
3284 top length. If the right length is not specified, it is
3285 taken to be the same as the top length.
3286
3287 Examples:
3288
3289 \snippet code/doc_src_stylesheet.qdoc 83
3290
3291 \row
3292 \li \b{Brush} \target Brush
3293 \li \l{#Color}{Color} \br
3294 | \l{Gradient} \br
3295 | \l{PaletteRole}
3296 \li Specifies a Color or a Gradient or an entry in the Palette.
3297
3298 \row
3299 \li \b{Color} \target Color
3300 \li \tt{rgb(\e{r}, \e{g}, \e{b})} \br
3301 | \tt{rgba(\e{r}, \e{g}, \e{b}, \e{a})} \br
3302 | \tt{hsv(\e{h}, \e{s}, \e{v})} \br
3303 | \tt{hsva(\e{h}, \e{s}, \e{v}, \e{a})} \br
3304 | \tt{hsl(\e{h}, \e{s}, \e{l})} \br
3305 | \tt{hsla(\e{h}, \e{s}, \e{l}, \e{a})} \br
3306 | \tt{#\e{rrggbb}} \br
3307 | \l{QColor::fromString()}{Color Name} \br
3308 \li Specifies a color as RGB (red, green, blue), RGBA (red,
3309 green, blue, alpha), HSV (hue, saturation, value), HSVA
3310 (hue, saturation, value, alpha), HSL (hue, saturation,
3311 lightness), HSLA (hue, saturation, lightness, alpha) or a
3312 named color. The \c rgb() or \c rgba() syntax can be used
3313 with integer values between 0 and 255, or with percentages.
3314 The value of s, v, l and a in \c hsv(), \c hsva() \c hsl()
3315 or \c hsla() must all be in the range 0-255 or with
3316 percentages, the value of h must be in the range 0-359.
3317 The support for HSL(A) is available since 5.13.
3318
3319 Examples:
3320
3321 \snippet code/doc_src_stylesheet.qdoc 84
3322
3323 \note The RGB colors allowed are the same as those allowed with
3324 CSS 2.1, as listed
3325 \l{http://www.w3.org/TR/CSS21/syndata.html#color-units}{here}.
3326
3327 \row
3328 \li \b{Font} \target Font
3329 \li (\l{#Font Style}{Font Style} | \l{#Font Weight}{Font Weight}){0,2} \l{#Font Size}{Font Size} String
3330 \li Shorthand font property.
3331
3332 \row
3333 \li \b{Font Size} \target Font Size
3334 \li \l{Length}
3335 \li The size of a font.
3336
3337 \row
3338 \li \b{Font Style} \target Font Style
3339 \li \c normal \br
3340 | \c italic \br
3341 | \c oblique
3342 \li The style of a font.
3343
3344 \row
3345 \li \b{Font Weight} \target Font Weight
3346 \li \c normal \br
3347 | \c bold \br
3348 | \c 100 \br
3349 | \c 200 \br
3350 ... \br
3351 | \c 900
3352 \li The weight of a font.
3353
3354 \row
3355 \li \b{Gradient} \target Gradient
3356 \li \c qlineargradient \br
3357 | \c qradialgradient \br
3358 | \c qconicalgradient
3359 \li Specifies gradient fills. There are three types of gradient fills:
3360
3361 \list
3362 \li \e{Linear} gradients interpolate colors between start and
3363 end points.
3364 \li \e{Radial} gradients interpolate colors between a focal
3365 point and end points on a circle surrounding it.
3366 \li \e{Conical} gradients interpolate colors around a center
3367 point.
3368 \endlist
3369
3370 Gradients are specified in Object Bounding Mode. Imagine the box
3371 in which the gradient is rendered, to have its top left corner at (0, 0)
3372 and its bottom right corner at (1, 1). Gradient parameters are
3373 then specified as percentages from 0 to 1. These values are
3374 extrapolated to actual box coordinates at runtime. It is possible
3375 specify values that lie outside the bounding box (-0.6 or 1.8, for
3376 instance).
3377
3378 \warning The stops have to appear sorted in ascending order.
3379
3380 Examples:
3381
3382 \snippet code/doc_src_stylesheet.qdoc 85
3383
3384 \row
3385 \li \b{Icon} \target Icon
3386 \li (\l{#Url}{Url} (\c disabled | \c active | \c normal | \c selected)?
3387 (\c on | \c off)? )*
3388 \li A list of url, QIcon::Mode and QIcon::State.
3389
3390 Example:
3391 \snippet code/doc_src_stylesheet.qdoc 86
3392
3393 \row
3394 \li \b{Length} \target Length
3395 \li \l{#Number}{Number} (\c px | \c pt | \c em | \c ex)?
3396 \li A number followed by a measurement unit. The CSS standard recommends
3397 that user agents must
3398 \l{http://www.w3.org/TR/CSS21/syndata.html#illegalvalues}{ignore}
3399 a declaration with an illegal value. In Qt, it is mandatory to
3400 specify measurement units. For compatibility with earlier versions
3401 of Qt, numbers without measurement units are treated as pixels
3402 in most contexts. The supported units are:
3403
3404 \list
3405 \li \c px: pixels
3406 \li \c pt: the size of one point (i.e., 1/72 of an inch)
3407 \li \c em: the size relative to the font size of the element
3408 (e.g., 2em means 2 times the size of the font)
3409 \li \c ex: the x-height of the font (i.e., the height of 'x')
3410 \endlist
3411
3412 However, Qt is limited to font sizes in \c pt and \c px and any other
3413 size must be in \c px, \c em or \c ex.
3414
3415 \row
3416 \li \b{Number} \target Number
3417 \li A decimal integer or a real number
3418 \li Examples: \c 0, \c 18, \c +127, \c -255, \c 12.34, \c -.5,
3419 \c 0009.
3420
3421 \row
3422 \li \b{Origin} \target Origin
3423 \li \c margin \br
3424 | \c border \br
3425 | \c padding \br
3426 | \c content
3427 \li Indicates which of four rectangles to use.
3428
3429 \list
3430 \li \c margin: The margin rectangle. The margin falls outside the border.
3431 \li \c border: The border rectangle. This is where any border is drawn.
3432 \li \c padding: The padding rectangle. Unlike the margins,
3433 padding is located inside the border.
3434 \li \c content: The content rectangle. This specifies where
3435 the actual contents go, excluding any
3436 padding, border, or margin.
3437 \endlist
3438
3439 See also \l{The Box Model}.
3440
3441 \row
3442 \li \b{PaletteRole} \target PaletteRole
3443 \li \c alternate-base \br
3444 | \c accent \br
3445 | \c base \br
3446 | \c bright-text \br
3447 | \c button \br
3448 | \c button-text \br
3449 | \c dark \br
3450 | \c highlight \br
3451 | \c highlighted-text \br
3452 | \c light \br
3453 | \c link \br
3454 | \c link-visited \br
3455 | \c mid \br
3456 | \c midlight \br
3457 | \c placeholder-text \br
3458 | \c shadow \br
3459 | \c text \br
3460 | \c tooltip-base \br
3461 | \c tooltip-text \br
3462 | \c window \br
3463 | \c window-text \br
3464 \li These values correspond the \l{QPalette::ColorRole}{Color roles}
3465 in the widget's QPalette.
3466
3467 For example,
3468 \snippet code/doc_src_stylesheet.qdoc 87
3469
3470 \row
3471 \li \b{Radius} \target Radius
3472 \li \l{#Length}{Length}\{1, 2\}
3473 \li One or two occurrences of \l{#Length}{Length}. If only one length is
3474 specified, it is used as the radius of the quarter circle
3475 defining the corner. If two lengths are specified, the
3476 first length is the horizontal radius of a quarter
3477 ellipse, whereas the second length is the vertical radius.
3478
3479 \row
3480 \li \b{Repeat} \target Repeat
3481 \li \c repeat-x \br
3482 | \c repeat-y \br
3483 | \c repeat \br
3484 | \c no-repeat
3485 \li A value indicating the nature of repetition.
3486
3487 \list
3488 \li \c repeat-x: Repeat horizontally.
3489 \li \c repeat-y: Repeat vertically.
3490 \li \c repeat: Repeat horizontally and vertically.
3491 \li \c no-repeat: Don't repeat.
3492 \endlist
3493
3494 \row
3495 \li \b{Url} \target Url
3496 \li \tt{url(\e{filename})}
3497 \li \tt{\e{filename}} is the name of a file on the local disk
3498 or stored using \l{The Qt Resource System}. Setting an
3499 image implicitly sets the width and height of the element.
3500
3501 \endtable
3502
3503 \section1 List of Pseudo-States
3504
3505 The following pseudo-states are supported:
3506
3507 \table 100%
3508 \header
3509 \li Pseudo-State
3510 \li Description
3511
3512 \row \li \c :active \target active
3513 \li This state is set when the widget resides in an active window.
3514
3515 \row
3516 \li \c :adjoins-item \target adjoins-item-ps
3517 \li This state is set when the \l{#branch-sub}{::branch} of a QTreeView
3518 is adjacent to an item.
3519
3520 \row
3521 \li \c :alternate \target alternate-ps
3522 \li This state is set for every alternate row whe painting the row of
3523 a QAbstractItemView when QAbstractItemView::alternatingRowColors()
3524 is set to true.
3525
3526 \row
3527 \li \c :bottom \target bottom-ps
3528 \li The item is positioned at the bottom. For example, a QTabBar
3529 that has its tabs positioned at the bottom.
3530
3531 \row
3532 \li \c :checked \target checked-ps
3533 \li The item is checked. For example, the
3534 \l{QAbstractButton::checked}{checked} state of QAbstractButton.
3535
3536 \row
3537 \li \c :closable \target closable-ps
3538 \li The items can be closed. For example, the QDockWidget has the
3539 QDockWidget::DockWidgetClosable feature turned on.
3540
3541 \row
3542 \li \c :closed \target closed-ps
3543 \li The item is in the closed state. For example, an non-expanded
3544 item in a QTreeView
3545
3546 \row
3547 \li \c :default \target default-ps
3548 \li The item is the default. For example, a
3549 \l{QPushButton::default}{default} QPushButton or a default action
3550 in a QMenu.
3551
3552 \row
3553 \li \c :disabled \target disabled-ps
3554 \li The item is \l{QWidget::enabled}{disabled}.
3555
3556 \row
3557 \li \c :editable \target editable-ps
3558 \li The QComboBox is editable.
3559
3560 \row
3561 \li \c :edit-focus \target edit-focus-ps
3562 \li The item has edit focus (See QStyle::State_HasEditFocus). This state
3563 is available only for Qt Extended applications.
3564
3565 \row
3566 \li \c :enabled \target enabled-ps
3567 \li The item is \l{QWidget::enabled}{enabled}.
3568
3569 \row
3570 \li \c :exclusive \target exclusive-ps
3571 \li The item is part of an exclusive item group. For example, a menu
3572 item in a exclusive QActionGroup.
3573
3574 \row
3575 \li \c :first \target first-ps
3576 \li The item is the first (in a list). For example, the first
3577 tab in a QTabBar.
3578
3579 \row
3580 \li \c :flat \target flat-ps
3581 \li The item is flat. For example, a
3582 \l{QPushButton::flat}{flat} QPushButton.
3583
3584 \row
3585 \li \c :floatable \target floatable-ps
3586 \li The items can be floated. For example, the QDockWidget has the
3587 QDockWidget::DockWidgetFloatable feature turned on.
3588
3589 \row
3590 \li \c :focus \target focus-ps
3591 \li The item has \l{QWidget::hasFocus()}{input focus}.
3592
3593 \row
3594 \li \c :has-children \target has-children-ps
3595 \li The item has children. For example, an item in a
3596 QTreeView that has child items.
3597
3598 \row
3599 \li \c :has-siblings \target has-siblings-ps
3600 \li The item has siblings. For example, an item in a
3601 QTreeView that siblings.
3602
3603 \row
3604 \li \c :horizontal \target horizontal-ps
3605 \li The item has horizontal orientation
3606
3607 \row
3608 \li \c :hover \target hover-ps
3609 \li The mouse is hovering over the item.
3610
3611 \row
3612 \li \c :indeterminate \target indeterminate-ps
3613 \li The item has indeterminate state. For example, a QCheckBox
3614 or QRadioButton is \l{Qt::PartiallyChecked}{partially checked}.
3615
3616 \row
3617 \li \c :last \target last-ps
3618 \li The item is the last (in a list). For example, the last
3619 tab in a QTabBar.
3620
3621 \row
3622 \li \c :left \target left-ps
3623 \li The item is positioned at the left. For example, a QTabBar
3624 that has its tabs positioned at the left.
3625
3626 \row
3627 \li \c :maximized \target maximized-ps
3628 \li The item is maximized. For example, a maximized QMdiSubWindow.
3629
3630 \row
3631 \li \c :middle \target middle-ps
3632 \li The item is in the middle (in a list). For example, a tab
3633 that is not in the beginning or the end in a QTabBar.
3634
3635 \row
3636 \li \c :minimized \target minimized-ps
3637 \li The item is minimized. For example, a minimized QMdiSubWindow.
3638
3639 \row
3640 \li \c :movable \target movable-ps
3641 \li The item can be moved around. For example, the QDockWidget has the
3642 QDockWidget::DockWidgetMovable feature turned on.
3643
3644 \row
3645 \li \c :no-frame \target no-frame-ps
3646 \li The item has no frame. For example, a frameless QSpinBox
3647 or QLineEdit.
3648
3649 \row
3650 \li \c :non-exclusive \target non-exclusive-ps
3651 \li The item is part of a non-exclusive item group. For example, a menu
3652 item in a non-exclusive QActionGroup.
3653
3654 \row
3655 \li \c :off \target off-ps
3656 \li For items that can be toggled, this applies to items
3657 in the "off" state.
3658
3659 \row
3660 \li \c :on \target on-ps
3661 \li For items that can be toggled, this applies to widgets
3662 in the "on" state.
3663
3664 \row
3665 \li \c :only-one \target only-one-ps
3666 \li The item is the only one (in a list). For example, a lone tab
3667 in a QTabBar.
3668
3669 \row
3670 \li \c :open \target open-ps
3671 \li The item is in the open state. For example, an expanded
3672 item in a QTreeView, or a QComboBox or QPushButton with
3673 an open menu.
3674
3675 \row
3676 \li \c :next-selected \target next-selected-ps
3677 \li The next item (in a list) is selected. For example, the
3678 selected tab of a QTabBar is next to this item.
3679
3680 \row
3681 \li \c :pressed \target pressed-ps
3682 \li The item is being pressed using the mouse.
3683
3684 \row
3685 \li \c :previous-selected \target previous-selected-ps
3686 \li The previous item (in a list) is selected. For example, a
3687 tab in a QTabBar that is next to the selected tab.
3688
3689 \row
3690 \li \c :read-only \target read-only-ps
3691 \li The item is marked read only or non-editable. For example,
3692 a read only QLineEdit or a non-editable QComboBox.
3693
3694 \row
3695 \li \c :right \target right-ps
3696 \li The item is positioned at the right. For example, a QTabBar
3697 that has its tabs positioned at the right.
3698
3699 \row
3700 \li \c :selected \target selected-ps
3701 \li The item is selected. For example, the selected tab in
3702 a QTabBar or the selected item in a QMenu.
3703
3704 \row
3705 \li \c :top \target top-ps
3706 \li The item is positioned at the top. For example, a QTabBar
3707 that has its tabs positioned at the top.
3708
3709 \row
3710 \li \c :unchecked \target unchecked-ps
3711 \li The item is
3712 \l{QAbstractButton::checked}{unchecked}.
3713
3714 \row
3715 \li \c :vertical \target vertical-ps
3716 \li The item has vertical orientation.
3717
3718 \row
3719 \li \c :window \target window-ps
3720 \li The widget is a window (i.e top level widget)
3721
3722 \endtable
3723
3724 \target subcontrols
3725 \section1 List of Sub-Controls
3726
3727 The following subcontrols are available:
3728
3729 \table 100%
3730 \header
3731 \li Sub-Control
3732 \li Description
3733
3734 \row
3735 \li \c ::add-line \target add-line-sub
3736 \li The button to add a line of a QScrollBar.
3737
3738 \row
3739 \li \c ::add-page \target add-page-sub
3740 \li The region between the handle (slider) and the \l{#add-line-sub}{add-line}
3741 of a QScrollBar.
3742
3743 \row
3744 \li \c ::branch \target branch-sub
3745 \li The branch indicator of a QTreeView.
3746
3747 \row
3748 \li \c ::chunk \target chunk-sub
3749 \li The progress chunk of a QProgressBar.
3750
3751 \row
3752 \li \c ::close-button \target close-button-sub
3753 \li The close button of a QDockWidget or tabs of QTabBar
3754
3755 \row
3756 \li \c ::corner \target corner-sub
3757 \li The corner between two scrollbars in a QAbstractScrollArea
3758
3759 \row
3760 \li \c ::down-arrow \target down-arrow-sub
3761 \li The down arrow of a QComboBox, QHeaderView (sort indicator),
3762 QScrollBar or QSpinBox.
3763
3764 \row
3765 \li \c ::down-button \target down-button-sub
3766 \li The down button of a QScrollBar or a QSpinBox.
3767
3768 \row
3769 \li \c ::drop-down \target drop-down-sub
3770 \li The drop-down button of a QComboBox.
3771
3772 \row
3773 \li \c ::float-button \target float-button-sub
3774 \li The float button of a QDockWidget
3775
3776 \row
3777 \li \c ::groove \target groove-sub
3778 \li The groove of a QSlider.
3779
3780 \row
3781 \li \c ::indicator \target indicator-sub
3782 \li The indicator of a QAbstractItemView, a QCheckBox, a QRadioButton,
3783 a checkable QMenu item or a checkable QGroupBox.
3784
3785 \row
3786 \li \c ::handle \target handle-sub
3787 \li The handle (slider) of a QScrollBar, a QSplitter, or a QSlider.
3788
3789 \row
3790 \li \c ::icon \target icon-sub
3791 \li The icon of a QAbstractItemView or a QMenu.
3792
3793 \row
3794 \li \c ::item \target item-sub
3795 \li An item of a QAbstractItemView, a QMenuBar, a QMenu, or
3796 a QStatusBar.
3797
3798 \row
3799 \li \c ::left-arrow \target left-arrow-sub
3800 \li The left arrow of a QScrollBar.
3801
3802 \row
3803 \li \c ::left-corner \target left-corner-sub
3804 \li The left corner of a QTabWidget. For example, this control can be
3805 used to control position the left corner widget in a QTabWidget.
3806
3807 \row
3808 \li \c ::menu-arrow \target menu-arrow-sub
3809 \li The arrow of a QToolButton with a menu.
3810
3811 \row
3812 \li \c ::menu-button \target menu-button-sub
3813 \li The menu button of a QToolButton.
3814
3815 \row
3816 \li \c ::menu-indicator \target menu-indicator-sub
3817 \li The menu indicator of a QPushButton.
3818
3819 \row
3820 \li \c ::right-arrow \target right-arrow-sub
3821 \li The right arrow of a QMenu or a QScrollBar.
3822
3823 \row
3824 \li \c ::pane \target pane-sub
3825 \li The pane (frame) of a QTabWidget.
3826
3827 \row
3828 \li \c ::right-corner \target right-corner-sub
3829 \li The right corner of a QTabWidget. For example, this control can be
3830 used to control the position the right corner widget in a QTabWidget.
3831
3832 \row
3833 \li \c ::scroller \target scroller-sub
3834 \li The scroller of a QMenu or QTabBar.
3835
3836 \row
3837 \li \c ::section \target section-sub
3838 \li The section of a QHeaderView.
3839
3840 \row
3841 \li \c ::separator \target separator-sub
3842 \li The separator of a QMenu or in a QMainWindow.
3843
3844 \row
3845 \li \c ::sub-line \target sub-line-sub
3846 \li The button to subtract a line of a QScrollBar.
3847
3848 \row
3849 \li \c ::sub-page \target sub-page-sub
3850 \li The region between the handle (slider) and the \l{#sub-line-sub}{sub-line}
3851 of a QScrollBar.
3852
3853 \row
3854 \li \c ::tab \target tab-sub
3855 \li The tab of a QTabBar or QToolBox.
3856
3857 \row
3858 \li \c ::tab-bar \target tab-bar-sub
3859 \li The tab bar of a QTabWidget. This subcontrol exists only to
3860 control the position of the QTabBar inside the QTabWidget. To
3861 style the tabs using the \l{#tab-sub}{::tab} subcontrol.
3862
3863 \row
3864 \li \c ::tear \target tear-sub
3865 \li The tear indicator of a QTabBar.
3866
3867 \row
3868 \li \c ::tearoff \target tearoff-sub
3869 \li The tear-off indicator of a QMenu.
3870
3871 \row
3872 \li \c ::text \target text-ps
3873 \li The text of a QAbstractItemView.
3874
3875 \row
3876 \li \c ::title \target title-sub
3877 \li The title of a QGroupBox or a QDockWidget.
3878
3879 \row
3880 \li \c ::up-arrow \target up-arrow-sub
3881 \li The up arrow of a QHeaderView (sort indicator), QScrollBar
3882 or a QSpinBox.
3883
3884 \row
3885 \li \c ::up-button \target up-button-sub
3886 \li The up button of a QSpinBox.
3887
3888 \endtable
3889
3890 See \l{Customizing the QPushButton's Menu Indicator Sub-Control}
3891 for an example of how to customize a subcontrol.
3892 */
3893
3894/*!
3895 \page stylesheet-examples.html
3896 \previouspage Qt Style Sheets Reference
3897 \title Qt Style Sheets Examples
3898
3899 We will now see a few examples to get started with using Qt Style Sheets.
3900
3901 \section1 Style Sheet Usage
3902
3903 \section2 Customizing the Foreground and Background Colors
3904
3905 Let's start by setting yellow as the background color of all
3906 \l{QLineEdit}s in an application. This could be achieved like
3907 this:
3908
3909 \snippet code/doc_src_stylesheet.cpp 88
3910
3911 If we want the property to apply only to the \l{QLineEdit}s that are
3912 children (or grandchildren or grand-grandchildren) of a specific dialog,
3913 we would rather do this:
3914
3915 \snippet code/doc_src_stylesheet.cpp 89
3916
3917 If we want the property to apply only to one specific QLineEdit,
3918 we can give it a name using QObject::setObjectName() and use an
3919 ID Selector to refer to it:
3920
3921 \snippet code/doc_src_stylesheet.cpp 90
3922
3923 Alternatively, we can set the
3924 \l{Qt Style Sheets Reference#background-prop}{background-color} property directly on the
3925 QLineEdit, omitting the selector:
3926
3927 \snippet code/doc_src_stylesheet.cpp 91
3928
3929 To ensure a good contrast, we should also specify a suitable
3930 color for the text:
3931
3932 \snippet code/doc_src_stylesheet.cpp 92
3933
3934 It might be a good idea to change the colors used for selected
3935 text as well:
3936
3937 \snippet code/doc_src_stylesheet.cpp 93
3938
3939
3940 \section2 Customizing Using Dynamic Properties
3941
3942 There are many situations where we need to present a form that
3943 has mandatory fields. To indicate to the user that the field is
3944 mandatory, one effective (albeit esthetically dubious) solution
3945 is to use yellow as the background color for those fields. It
3946 turns out this is very easy to implement using Qt Style Sheets.
3947 First, we would use the following application-wide style sheet:
3948
3949 \snippet code/doc_src_stylesheet.qdoc 94
3950
3951 This means that every widget whose \c mandatoryField Qt property
3952 is set to true would have a yellow background.
3953
3954 Then, for each mandatory field widget, we would simply create a
3955 \c mandatoryField property on the fly and set it to true. For
3956 example:
3957
3958 \snippet code/doc_src_stylesheet.cpp 95
3959
3960 \section2 Customizing a QPushButton Using the Box Model
3961
3962 This time, we will show how to create a red QPushButton. This
3963 QPushButton would presumably be connected to a very destructive
3964 piece of code.
3965
3966 First, we are tempted to use this style sheet:
3967
3968 \snippet code/doc_src_stylesheet.qdoc 96
3969
3970 However, the result is a boring, flat button with no borders:
3971
3972 \image stylesheet-redbutton1.png {Flat red button}
3973
3974 What happened is this:
3975
3976 \list
3977 \li We have made a request that cannot be satisfied using the
3978 native styles alone (e.g., the Windows Vista theme engine doesn't
3979 let us specify the background color of a button).
3980 \li Therefore, the button is rendered using style sheets.
3981 \li We haven't specified any values for
3982 \l{Qt Style Sheets Reference#border-width-prop}{border-width} and
3983 \l{Qt Style Sheets Reference#border-style-prop}{border-style}, so by default we obtain
3984 a 0-pixel wide border of style \c none.
3985 \endlist
3986
3987 Let's improve the situation by specifying a border:
3988
3989 \snippet code/doc_src_stylesheet.qdoc 97
3990
3991 \image stylesheet-redbutton2.png {Red button with a beige border}
3992
3993 Things look already a lot better. But the button looks a bit
3994 cramped. Let's specify some spacing between the border and the
3995 text using the \l{Qt Style Sheets Reference#padding-prop}{padding}. Additionally, we will
3996 enforce a minimum width, round the corners, and specify a larger
3997 font to make the button look nicer:
3998
3999 \snippet code/doc_src_stylesheet.qdoc 98
4000
4001 \image stylesheet-redbutton3.png
4002 {Red button with a round beige border and big, bold text}
4003
4004 The only issue remaining is that the button doesn't react when we
4005 press it. We can fix this by specifying a slightly different
4006 background color and use a different border style.
4007
4008 \snippet code/doc_src_stylesheet.qdoc 99
4009
4010 \section2 Customizing the QPushButton's Menu Indicator Sub-Control
4011
4012 Subcontrols give access to the sub-elements of a widget. For
4013 example, a QPushButton associated with a menu (using
4014 QPushButton::setMenu()) has a menu indicator. Let's customize
4015 the menu indicator for the red push button:
4016
4017 \snippet code/doc_src_stylesheet.qdoc 100
4018
4019 By default, the menu indicator is located at the bottom-right
4020 corner of the padding rectangle. We can change this by specifying
4021 \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position} and
4022 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} to anchor the
4023 indicator differently. We can also use \l{Qt Style Sheets Reference#top-prop}{top} and
4024 \l{Qt Style Sheets Reference#left-prop}{left} to move the indicator by a few pixels. For
4025 example:
4026
4027 \snippet code/doc_src_stylesheet.qdoc 101
4028
4029 This positions the \c myindicator.png to the center right of the
4030 QPushButton's \l{Qt Style Sheets Reference#padding-prop}{padding} rectangle (see
4031 \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} for more
4032 information).
4033
4034 \section2 Complex Selector Example
4035
4036 Since red seems to be our favorite color, let's make the text in
4037 QLineEdit red by setting the following application-wide
4038 stylesheet:
4039
4040 \snippet code/doc_src_stylesheet.qdoc 102
4041
4042 However, we would like to give a visual indication that a
4043 QLineEdit is read-only by making it appear gray:
4044
4045 \snippet code/doc_src_stylesheet.qdoc 103
4046
4047 At some point, our design team comes with the requirement that
4048 all \l{QLineEdit}s in the registration form (with the
4049 \l{QObject::objectName}{object name} \c registrationDialog) to be
4050 brown:
4051
4052 \snippet code/doc_src_stylesheet.qdoc 104
4053
4054 A few UI design meetings later, we decide that all our
4055 \l{QDialog}s should have brown colored \l{QLineEdit}s:
4056
4057 \snippet code/doc_src_stylesheet.qdoc 105
4058
4059 Quiz: What happens if we have a read-only QLineEdit in a QDialog?
4060 [Hint: The \l{The Style Sheet Syntax#Conflict Resolution}{Conflict Resolution} section above explains
4061 what happens in cases like this.]
4062
4063 \section1 Customizing Specific Widgets
4064
4065 This section provides examples to customize specific widgets using Style Sheets.
4066
4067 \section2 Customizing QAbstractScrollArea
4068
4069 The background of any QAbstractScrollArea (Item views, QTextEdit
4070 and QTextBrowser) can be set using the background properties. For example,
4071 to set a background-image that scrolls with the scroll bar:
4072 \snippet code/doc_src_stylesheet.qdoc 106
4073
4074 If the background-image is to be fixed with the viewport:
4075 \snippet code/doc_src_stylesheet.qdoc 107
4076
4077 \section2 Customizing QCheckBox
4078
4079 Styling of a QCheckBox is almost identical to styling a QRadioButton. The
4080 main difference is that a tristate QCheckBox has an indeterminate state.
4081
4082 \snippet code/doc_src_stylesheet.qdoc 108
4083
4084 \section2 Customizing QComboBox
4085
4086 We will look at an example where the drop down button of a QComboBox
4087 appears "merged" with the combo box frame.
4088
4089 \snippet code/doc_src_stylesheet.qdoc 109
4090
4091 The pop-up of the QComboBox is a QAbstractItemView and is styled using
4092 the descendant selector:
4093 \snippet code/doc_src_stylesheet.qdoc 110
4094
4095 \section2 Customizing QDockWidget
4096
4097 The title bar and the buttons of a QDockWidget can be customized as
4098 follows:
4099
4100 \snippet code/doc_src_stylesheet.qdoc 111
4101
4102 If one desires to move the dock widget buttons to the left, the following
4103 style sheet can be used:
4104
4105 \snippet code/doc_src_stylesheet.qdoc 112
4106
4107 \note To customize the separator (resize handle) of a QDockWidget,
4108 use QMainWindow::separator.
4109
4110 \section2 Customizing QFrame
4111
4112 A QFrame is styled using the \l{The Box Model}.
4113
4114 \snippet code/doc_src_stylesheet.qdoc 113
4115
4116 \section2 Customizing QGroupBox
4117
4118 Let us look at an example that moves the QGroupBox's title to
4119 the center.
4120
4121 \snippet code/doc_src_stylesheet.qdoc 114
4122
4123 For a checkable QGroupBox, use the \{#indicator-sub}{::indicator} subcontrol
4124 and style it exactly like a QCheckBox (i.e)
4125
4126 \snippet code/doc_src_stylesheet.qdoc 115
4127
4128 \section2 Customizing QHeaderView
4129
4130 QHeaderView is customized as follows:
4131
4132 \snippet code/doc_src_stylesheet.qdoc 116
4133
4134 \section2 Customizing QLineEdit
4135
4136 The frame of a QLineEdit is styled using the \l{The Box Model}. To
4137 create a line edit with rounded corners, we can set:
4138 \snippet code/doc_src_stylesheet.qdoc 117
4139
4140 The password character of line edits that have QLineEdit::Password
4141 echo mode can be set using:
4142 \snippet code/doc_src_stylesheet.qdoc 118
4143
4144 The background of a read only QLineEdit can be modified as below:
4145 \snippet code/doc_src_stylesheet.qdoc 119
4146
4147 \section2 Customizing QListView
4148
4149 The background color of alternating rows can be customized using the following
4150 style sheet:
4151
4152 \snippet code/doc_src_stylesheet.qdoc 120
4153
4154 To provide a special background when you hover over items, we can use the
4155 \l{item-sub}{::item} subcontrol. For example,
4156
4157 \snippet code/doc_src_stylesheet.qdoc 121
4158
4159 \section2 Customizing QMainWindow
4160
4161 The separator of a QMainWindow can be styled as follows:
4162
4163 \snippet code/doc_src_stylesheet.qdoc 122
4164
4165 \section2 Customizing QMenu
4166
4167 Individual items of a QMenu are styled using the 'item' subcontrol as
4168 follows:
4169
4170 \snippet code/doc_src_stylesheet.qdoc 123
4171
4172 For a more advanced customization, use a style sheet as follows:
4173
4174 \snippet code/doc_src_stylesheet.qdoc 124
4175
4176 \section2 Customizing QMenuBar
4177
4178 QMenuBar is styled as follows:
4179
4180 \snippet code/doc_src_stylesheet.qdoc 125
4181
4182 \section2 Customizing QProgressBar
4183
4184 The QProgressBar's \l{stylesheet-reference.html#border-prop}{border},
4185 \l{stylesheet-reference.html#chunk-sub}{chunk}, and
4186 \l{stylesheet-reference.html#text-align-prop}{text-align} can be customized using
4187 style sheets. However, if one property or sub-control is customized,
4188 all the other properties or sub-controls must be customized as well.
4189
4190 \image progressBar-stylesheet.png {Progress bar showing 30%}
4191
4192 For example, we change the \l{stylesheet-reference.html#border-prop}
4193 {border} to grey and the \l{stylesheet-reference.html#chunk-sub}{chunk}
4194 to cerulean.
4195
4196 \snippet code/doc_src_stylesheet.qdoc 126
4197
4198 This leaves the \l{stylesheet-reference.html#text-align-prop}
4199 {text-align}, which we customize by positioning the text in the center of
4200 the progress bar.
4201
4202 \snippet code/doc_src_stylesheet.qdoc 127
4203
4204 A \l{stylesheet-reference.html#margin-prop}{margin} can be included to
4205 obtain more visible chunks.
4206
4207 \image progressBar2-stylesheet.png {Notched progress bar}
4208
4209 In the screenshot above, we use a
4210 \l{stylesheet-reference.html#margin-prop}{margin} of 0.5 pixels.
4211
4212 \snippet code/doc_src_stylesheet.qdoc 128
4213
4214 \section2 Customizing QPushButton
4215
4216 A QPushButton is styled as follows:
4217 \snippet code/doc_src_stylesheet.qdoc 129
4218
4219 For a QPushButton with a menu, use the
4220 \l{Qt Style Sheets Reference#menu-indicator-sub}{::menu-indicator}
4221 subcontrol.
4222
4223 \snippet code/doc_src_stylesheet.qdoc 130
4224
4225 Checkable QPushButton have the \l{Qt Style Sheets Reference#checked-ps}
4226 {:checked} pseudo state set.
4227
4228 \section2 Customizing QRadioButton
4229
4230 The indicator of a QRadioButton can be changed using:
4231 \snippet code/doc_src_stylesheet.qdoc 131
4232
4233 \section2 Customizing QScrollBar
4234
4235 The QScrollBar can be styled using its subcontrols like
4236 \l{stylesheet-reference.html#handle-sub}{handle},
4237 \l{stylesheet-reference.html#add-line-sub}{add-line},
4238 \l{stylesheet-reference.html#sub-line-sub}{sub-line}, and so on. Note that
4239 if one property or sub-control is customized, all the other properties or
4240 sub-controls must be customized as well.
4241
4242 \image stylesheet-scrollbar1.png {Green stylized scroll bar}
4243
4244 The scroll bar above has been styled in aquamarine with a solid grey
4245 border.
4246
4247 \snippet code/doc_src_stylesheet.qdoc 132
4248
4249 \snippet code/doc_src_stylesheet.qdoc 133
4250
4251 \snippet code/doc_src_stylesheet.qdoc 134
4252
4253 The \l{stylesheet-reference.html#left-arrow-sub}{left-arrow} and
4254 \l{stylesheet-reference.html#right-arrow-sub}{right-arrow} have a solid grey
4255 border with a white background. As an alternative, you could also embed the
4256 image of an arrow.
4257
4258 \snippet code/doc_src_stylesheet.qdoc 135
4259
4260 If you want the scroll buttons of the scroll bar to be placed together
4261 (instead of the edges) like on \macos, you can use the following
4262 stylesheet:
4263 \snippet code/doc_src_stylesheet.qdoc 136
4264
4265 The scroll bar using the above stylesheet looks like this:
4266 \image stylesheet-scrollbar2.png {Colorized scroll bar}
4267
4268
4269 To customize a vertical scroll bar use a style sheet similar to the following:
4270 \snippet code/doc_src_stylesheet.qdoc 137
4271
4272 \section2 Customizing QSizeGrip
4273
4274 QSizeGrip is usually styled by just setting an image.
4275
4276 \snippet code/doc_src_stylesheet.qdoc 138
4277
4278 \section2 Customizing QSlider
4279
4280 You can style horizontal slider as below:
4281 \snippet code/doc_src_stylesheet.qdoc 139
4282
4283 If you want to change the color of the slider parts before and after the handle, you can use the add-page
4284 and sub-page subcontrols. For example, for a vertical slider:
4285
4286 \snippet code/doc_src_stylesheet.qdoc 140
4287
4288 \section2 Customizing QSpinBox
4289
4290 QSpinBox can be completely customized as below (the style sheet has commentary inline):
4291
4292 \snippet code/doc_src_stylesheet.qdoc 141
4293
4294
4295 \section2 Customizing QSplitter
4296
4297 A QSplitter derives from a QFrame and hence can be styled like a QFrame.
4298 The grip or the handle is customized using the
4299 \l{Qt Style Sheets Reference#handle-sub}{::handle} subcontrol.
4300
4301 \snippet code/doc_src_stylesheet.qdoc 142
4302
4303 \section2 Customizing QStatusBar
4304
4305 We can provide a background for the status bar and a border for items
4306 inside the status bar as follows:
4307 \snippet code/doc_src_stylesheet.qdoc 143
4308
4309 Note that widgets that have been added to the QStatusBar can be styled
4310 using the descendant declaration (i.e)
4311 \snippet code/doc_src_stylesheet.qdoc 144
4312
4313 \section2 Customizing QTabWidget and QTabBar
4314
4315 \image tabWidget-stylesheet1.png {Image of several tabs}
4316
4317 For the screenshot above, we need a stylesheet as follows:
4318
4319 \snippet code/doc_src_stylesheet.qdoc 145
4320
4321 Often we require the tabs to overlap to look like below:
4322 \image tabWidget-stylesheet2.png {Image of overlapped tabs}
4323
4324 For a tab widget that looks like above, we make use of
4325 \l{https://doc.qt.io/qt-5/stylesheet-customizing.html#the-box-model}
4326 {negative margins}. Negative values draw the element closer to its
4327 neighbors than it would be by default. The resulting stylesheet
4328 looks like this:
4329
4330 \snippet code/doc_src_stylesheet.qdoc 146
4331
4332 To move the tab bar to the center (as below), we require the following stylesheet:
4333 \image tabWidget-stylesheet3.png {Several tabs centered in the widget}
4334
4335 \snippet code/doc_src_stylesheet.qdoc 147
4336
4337 The tear indicator and the scroll buttons can be further customized as follows:
4338 \snippet code/doc_src_stylesheet.qdoc 148
4339
4340 Since Qt 4.6 the close button can be customized as follow:
4341 \snippet code/doc_src_stylesheet.qdoc 159
4342
4343 \section2 Customizing QTableView
4344
4345 Suppose we'd like our selected item in QTableView to have bubblegum pink
4346 fade to white as its background.
4347
4348 \image tableWidget-stylesheet.png {Table view with custom style}
4349
4350 This is possible with the
4351 \l{stylesheet-reference.html#selection-background-color-prop}
4352 {selection-background-color} property and the syntax required is:
4353
4354 \snippet code/doc_src_stylesheet.qdoc 149
4355
4356 The corner widget can be customized using the following style sheet
4357
4358 \snippet code/doc_src_stylesheet.qdoc 150
4359
4360 The QTableView's checkbox indicator can also be customized. In the
4361 following snippet the indicator \c background-color in unchecked state is
4362 customized:
4363
4364 \snippet code/doc_src_stylesheet.qdoc 161
4365
4366 \section2 Customizing QToolBar
4367
4368 The background and the handle of a QToolBar is customized as below:
4369 \snippet code/doc_src_stylesheet.qdoc 151
4370
4371 \section2 Customizing QToolBox
4372
4373 The tabs of the QToolBox are customized using the 'tab' subcontrol.
4374
4375 \snippet code/doc_src_stylesheet.qdoc 152
4376
4377 \section2 Customizing QToolButton
4378
4379 There are three types of QToolButtons.
4380 \list
4381 \li The QToolButton has no menu. In this case, the QToolButton is styled
4382 exactly like QPushButton. See
4383 \l{#Customizing QPushButton}{Customizing QPushButton} for an
4384 example.
4385
4386 \li The QToolButton has a menu and has the QToolButton::popupMode set to
4387 QToolButton::DelayedPopup or QToolButton::InstantPopup. In this case,
4388 the QToolButton is styled exactly like a QPushButton with a menu.
4389 See \l{#Customizing QPushButton}{Customizing QPushButton} for an
4390 example of the usage of the menu-indicator pseudo state.
4391
4392 \li The QToolButton has its QToolButton::popupMode set to
4393 QToolButton::MenuButtonPopup. In this case, we style it as follows:
4394 \endlist
4395
4396 \snippet code/doc_src_stylesheet.qdoc 153
4397
4398
4399 \section2 Customizing QToolTip
4400
4401 QToolTip is customized exactly like a QLabel. In addition, for platforms
4402 that support it, the opacity property may be set to adjust the opacity.
4403
4404 For example,
4405 \snippet code/doc_src_stylesheet.qdoc 154
4406
4407 \section2 Customizing QTreeView
4408
4409 The background color of alternating rows can be customized using the following
4410 style sheet:
4411
4412 \snippet code/doc_src_stylesheet.qdoc 155
4413
4414 To provide a special background when you hover over items, we can use the
4415 \l{item-sub}{::item} subcontrol. For example,
4416 \snippet code/doc_src_stylesheet.qdoc 156
4417
4418 The branches of a QTreeView are styled using the
4419 \l{Qt Style Sheets Reference#branch-sub}{::branch} subcontrol. The
4420 following stylesheet color codes the various states when drawing
4421 a branch.
4422
4423 \snippet code/doc_src_stylesheet.qdoc 157
4424
4425 Colorful, though it is, a more useful example can be made using the
4426 following images:
4427
4428 \table
4429 \row
4430 \li \inlineimage stylesheet-vline.png {Vertical line}
4431 \li \inlineimage stylesheet-branch-more.png {Junction line for lists}
4432 \li \inlineimage stylesheet-branch-end.png {Line for terminating the list}
4433 \li \inlineimage stylesheet-branch-closed.png {Arrow pointing right}
4434 \li \inlineimage stylesheet-branch-open.png {Arrow pointing down}
4435 \row
4436 \li vline.png
4437 \li branch-more.png
4438 \li branch-end.png
4439 \li branch-closed.png
4440 \li branch-open.png
4441 \endtable
4442
4443 \snippet code/doc_src_stylesheet.qdoc 158
4444
4445 The resulting tree view looks like this:
4446
4447 \image stylesheet-treeview.png {Tree view with styled branches}
4448
4449 \sa {Supported HTML Subset}, QStyle
4450
4451
4452 \section1 Common Mistakes
4453
4454 This section lists some common mistakes when using stylesheets.
4455
4456 \section2 QPushButton and images
4457
4458 When styling a QPushButton, it is often desirable to use an image as the
4459 button graphic. It is common to try the
4460 \l{Qt Style Sheets Reference#background-image-prop}{background-image}
4461 property,
4462 but this has a number of drawbacks: For instance, the background will
4463 often appear hidden behind the button decoration, because it is not
4464 considered a background. In addition, if the button is resized, the
4465 entire background will be stretched or tiled, which does not
4466 always look good.
4467
4468 It is better to use the
4469 \l{Qt Style Sheets Reference#border-image-prop}{border-image}
4470 property, as it will always display the image,
4471 regardless of the background (you can combine it with a background if it
4472 has alpha values in it), and it has special settings to deal with button
4473 resizing.
4474
4475 Consider the following snippet:
4476
4477 \snippet stylesheet/common-mistakes.cpp 1
4478
4479 This will produce a button looking like this:
4480
4481 \image stylesheet-border-image-normal.png {Button with a background}
4482
4483 The numbers after the url gives the top, right, bottom and left number of
4484 pixels, respectively. These numbers correspond to the border and should not
4485 stretch when the size changes.
4486 Whenever you resize the button, the middle part of the image will stretch
4487 in both directions, while the pixels specified in the stylesheet
4488 will not. This makes the borders of the button look more natural, like
4489 this:
4490
4491 \image stylesheet-border-image-stretched.png
4492 {Button with specified border sizes}
4493 \caption With borders
4494
4495 \image stylesheet-border-image-wrong.png
4496 {Button without specified border sizes}
4497 \caption Without borders
4498
4499 */