Custom Looks using Qt Style Sheets

With the introduction of QT Style Sheets, styling qt widgets have become a lot simpler. Whether just need to customize the look for an existing widgets or design a whole new style from scratch, there are now a n Alternative to subclassing Qstyle.

• What is Qt Style Sheets?
• Basic Style Sheet Syntax
• The Box Model
• Foregrounds and backgrounds
• Creating Scalable Styles
• Controlling the Size
• Handling Pseudo-states
• Micro customization using Subcontrols

What is Qt Style Sheets?

Qt style Sheets is heavily inspired by HTML cascading Style Sheets (CSS) but adapted to widgets. can set a style sheet on a individual child widget, on a whole window, or even on a whole application by calling Qwid Get::setstylesheet () or Qapplication::setstylesheet ().

Under the hood, style sheets is implemented by a special Qstyle subclass called Qstylesheetstyle that acts as a wrapper f or the platform-specific style. This special style applies any customizations specified using style sheets on top of the underlying platform-specific Styl E.

Qt 4.2 includes a stylesheet example that lets your experiment with style sheets. It comes with the styles, Coffee and Pagefold.

The Coffee style shown above customizes the look of push buttons, frames, labels, and ToolTips, but lets the underlying St YLE (e.g., Windows XP) Draw checkboxes, ComboBoxes, and radio buttons.

In contrast, Pagefold fully redefines the look of all controls used in the dialog, resulting in a distinctive, platform-in Dependent look.

This article was meant to being a quick introduction to style sheets. For a all description of the Qt Style Sheet syntax, please refer to the online documentation or try out the Styleshee t example, located in Qt 4.2 ' s examples/widgets directory.

Basic Style Sheet Syntax

The Qt Style Sheet syntactic rules are almost the same as those of CSS. If you already know CSS, you can probably skip to the next section.

A style sheet consists of a sequence of style rules. Each rule has the form

selector {Attribute:value}

The "selector" part was typically a class name (e.g., qcombobox), but other syntaxes was possible. The "attribute" part was the name of a style sheet attribute, and "value" is the value of which is assigned to the attribute.

For convenience, we can use the shorthand notation

Selector1, Selector2, ..., selectorm {    attribute1:value1;    attribute2:value2;    ...    Attributen:valuen;}

Which simultaneously sets N attributes on any widget this matches any of the M selectors. For example,

Qcheckbox, Qcombobox, qspinbox {    color:red;    Background-color:white;    Font:bold;}

Sets the foreground and background colors and the fonts of all qcheckboxes, qcomboboxes, and qspinboxes.

The online documentation lists the supported attributes for each widget type. In this article, we'll concentrate on the most common attributes.

The Box Model

When using style sheets, every widgets is treated as a box with four concentric rectangles:the margin rectangle, the Borde R rectangle, the padding rectangle, and the content rectangle. For a plain widget &emdash; i.e., a widget with a 0-pixel margins, a 0-pixel thick border, and 0 pixels of padding &emdash; These four rectangles coincide exactly.

The margin area was outside the border and is always transparent. The border provides a frame for the widget. Several built-in frame styles, including Inset,outset, solid, and Ridge, is available by setting the Border-style Attribu Te. The padding provides spacing between the border and the content area.

Foregrounds and backgrounds

The foreground color (the color used for drawing text) of the widgets is specified using the color attribute. The background color, specified using Background-color, fills the padding rectangle of the widget.

The background image, specified using Background-image, is drawn in the rectangular area (margin, border, content or Paddi ng rectangle) specified by Background-origin.  The alignment and tiling of the background image within the rectangular area is modified using the background-position and Background-repeat attribute respectively.

If We specify a background image with an alpha channel (for semi-transparency), the color specified using Background-color would shine through. This can is used to reuse the same background image in a variety of contexts.

The following example illustrates the usage of the attributes seen so far:

qframe {    margin:10px;    border:2px solid Green;    padding:20px;    Background-color:gray;    Background-image:url (qt.png);    Background-position:top right;    background-origin:content;    Background-repeat:none;}

In this example, the specified margin, border, and padding apply uniformly to all four sides of all qframes in the Applica tion. The margin attribute can be used to specify different top, right, bottom, and left values if we want:

qframe {    margin:14px 18px 20px 18px;}

Alternatively, we can use the Margin-top, Margin-right, Margin-bottom, and Margin-left attributes:

qframe {    margin-top:14px;    margin-right:18px;    margin-bottom:20px;    margin-left:18px;}

Although we have used qframe in the examples above, we could has specified any Qt widgets that supports the box model, Inc. Luding Qcheckbox, Qlabel,qlineedit, Qlistview, Qmenu, Qpushbutton, Qtextedit, and Qtooltip.

Creating Scalable Styles

By default, background images specified using Background-image is repeated as many times as necessary, both horizontally and vertically, to cover the widgets ' s padding rectangle (i.e., the area inside the border). If we want to create backgrounds this scale nicely depending on the widget's size, we need to specify a so-called "border Image ".

Border images is specified using the Border-image attribute. They provide both the border and the background of the widget. A border image is cut to nine cells, a bit like a tic-tac-toe board:

When filling the border of a widgets, the four corner cells be taken more or less ' as is ', whereas the other five cells AR E either stretched or tiled to fill the available space.

When specifying a border image, we must specify the four "cuts" that define the nine cells, in addition to the border imag E itself. We must also specify whether we want the non-corner cells to being stretched or tiled, and we must set border-width so that I T corresponds to the cuts (to avoid scaling the corners).

For example, here's the style sheet necessary to produce the above push button (shown in four different sizes):

Qpushbutton {    border-width:4px;    Border-image:url (Button.png) 4 4 4 4 stretch stretch;}

As in the case of a background image, the border image is a alpha channel that is blends with the background-color.

Controlling the Size

The Min-width and Min-height attributes can be used to specify the minimum width and height of the contents area of a WIDG Et. These values affect Theminimumsizehint () of a widget, which'll be honored by the layout. For example:

Qpushbutton {    min-width:68px;    min-height:28px;}

If This attribute isn't specified, the minimum height is derived from the widget's contents and the current style.

Handling Pseudo-states

The look of widgets can is customized for specific user interface states by specifying so-called pseudo-states in the Styl E sheet. For example, we could prefer to give a push button a sunken look when it was pressed by the user by specifying the:P ressed p Seudo-state:

Qpushbutton {    border:2px outset green;    Background:gray;} qpushbutton:pressed {    border-style:inset;}

Here's the list of available pseudo-states:

pseudo-state	Description
: Checked	The button widget is checked.
:d isabled	The widget is disabled.
: Enabled	The widget is enabled.
: Focus	The widget has input focus.
: hover	The mouse is hovering over the widget.
: Indeterminate	The checkbox or RadioButton is partially checked.
: Off	For widgets that can is toggled, this applies to widgets in the ' off ' state.
: On	For widgets that can is toggled, this applies to widgets in the ' on ' state. This also applies to comboboxes that has their list open, and to menu bars, which has one of the their menus open.
:p ressed	The widget is being pressed using the mouse.
: Unchecked	The button widget is unchecked.

Micro customization using Subcontrols

Many widgets contain embedded elements, sometimes called "Subcontrols". The up and down arrows of a spin box is typical examples of subcontrols.

Subcontrols can be specified using:: (e.g., Qdatetimeedit::up-button). Styling them is very similar to styling widgets. They follow the box model described above (i.e., they can has a border, a background, etc.) and can be combined with Pseu Do-states (e.g., qspinbox::up-button:hover).

The table below lists the subcontrols that is available to style sheet authors:

Subcontrol	Description
::d Own-arrow	The down arrow of a combo or spin box.
::d Own-button	The down button of a spin box.
::d Rop-down	The drop-down arrow of a ComboBox.
:: Indicator	The indicator of a checkbox, a radio button, or a checkable group box.
:: Item	A menu, menu bar, or status bar item.
:: Menu-indicator	The menu indicator of a push button.
:: Title	The title of a group box.
:: Up-arrow	The up arrow of a spin box.
:: Up-button	The up button of a spin box.

Subcontrols May is placed anywhere in the widget box using Subcontrol-position and Subcontrol-origin. The positioning of the subcontrol is further fine tuned using absolute or relative positioning. The choice of positioning technique depends on whether the Subcontrol have a fixed size or have a size that was dependent on The widget ' s box.

Relative positioning

Relative positioning is suitable for subcontrols that has a fixed size (specified using the width and height attributes). Using this technique, the Subcontrol is moved by a offset from the position that is defined using Subcontrol-positi On and Subcontrol-origin. The left attribute is used to move the subcontrol to the right and top attribute is used to move the Subcontrol to The bottom. For example:

Qpushbutton::menu-indicator {    image:url (menu_indicator.png);    width:13px;    height:13px;    subcontrol-origin:padding;    Subcontrol-position:bottom right;}

When the user presses a button, we can move the menu indicator from its original position by a few pixels to the bottom ri Ght to simulate a button press:

qpushbutton::menu-indicator:pressed {    position:relative;    top:2px;    left:2px;}

Absolute positioning

Absolute positioning is suitable for subcontrols with a size that depends on the size of the widget ' s box. As before, Subcontrol-origin is used to define a rectangle of reference in the widget ' s box. The rectangular area for the subcontrol are then defined by providing offsets from the top, right, bottom, and left edges O F This reference rectangle:

Qpushbutton::menu-indicator {    border:2px solid red;    subcontrol-origin:padding;    Position:absolute;    top:2px;    right:2px;    bottom:2px;    left:40px;}

For Subcontrols that has a fixed width or a fixed height, the subcontrol-position maybe used to specify an alignment with In the Subcontrol-origin rectangle:

Qpushbutton::menu-indicator {    image:url (menu_indicator.png);    width:13px;    subcontrol-origin:padding;    Subcontrol-position:bottom right;    position:relative;    top:2px;    bottom:2px;    right:2px;}

Custom Looks using Qt Style Sheets