Difference between revisions of "Dynamic Properties and Stylesheets"

From Qt Wiki
Jump to: navigation, search
(Cleanup)
(restructure some parts to make the page function better as a whole, simplify/harmonize the code examples, clarify the connection from the limitations text to the suggested workaround, etc.)
Line 3: Line 3:
 
== Introduction ==
 
== Introduction ==
  
Stylesheets makes it possible to customize the look of Qt applications without having to master the magic behind Qt styles. For lighter tweaks, to the quite complex, stylesheets can do the job. For the real unique user experience, QtQuick and {{DocLink|QGraphicsView}} is a better choice.
+
Qt stylesheets make it possible to customize the look of Qt applications without having to master the magic behind Qt styles. From lighter tweaks to the quite complex, stylesheets can do the job. For a fully customized and unique user experience, QtQuick and {{DocLink|QGraphicsView}} are a better choice.
  
When using stylesheets, styles are applied using selectors. For instance, the snippet below gives all {{DocLink|QLineEdit}} widgets a yellow background color, if this style sheet is set on the form widget. Here, the selector is the word <tt>QLineEdit</tt>.
+
When using stylesheets, styles are applied using selectors. For instance, the snippet below gives all {{DocLink|QLineEdit}} widgets a yellow background color, if this style sheet is set on the form widget or on a widget that contains it. Here, the selector is the word <tt>QLineEdit</tt>:
  
 
<code>
 
<code>
 
QLineEdit
 
QLineEdit
 
{
 
{
background: yellow;
+
  background: yellow;
 
}
 
}
 
</code>
 
</code>
Line 16: Line 16:
 
There are numerous selectors based on object names, sub-controls, pseudo-states and more. These can be used to change the look of a user interface and also make all {{DocLink|QPushButton}} widgets named ''okButton'' have green text, and so on.
 
There are numerous selectors based on object names, sub-controls, pseudo-states and more. These can be used to change the look of a user interface and also make all {{DocLink|QPushButton}} widgets named ''okButton'' have green text, and so on.
  
For dynamic changes in the user interface look, the property value selector can be used in combination with dynamic properties. Dynamic properties was introduced in Qt 4.2 and allows your to assign property values to {{DocLink|QObject}}s for properties that do not exist at compile time. I.e. if you choose to set the a property called ''urgent'' to true for a {{DocLink|QObject}}, that property will stick even tough the class does not contain a <tt>Q_PROPERTY</tt> macro for the property ''urgent''.
+
== Custom properties ==
 +
 
 +
For dynamic changes in the user interface look, the property value selector can be used in combination with dynamic properties. Dynamic properties were introduced in Qt 4.2 and allow you to assign property values to {{DocLink|QObject}}s for properties that do not exist at compile time. I.e. if you choose to set the a property called ''urgent'' to true for a {{DocLink|QObject}}, that property will stick even tough the class does not contain a <tt>Q_PROPERTY</tt> macro for the property ''urgent''.
  
 
Creating a stylesheet selector relying on a dynamic property, e.g. ''urgent'', makes it possible to highlight parts of the user interface in a very dynamic manner. For instance, adding the following rule to the stylesheet above will given any {{DocLink|QLineEdit}} with the ''urgent'' property set to true red text on a yellow background.
 
Creating a stylesheet selector relying on a dynamic property, e.g. ''urgent'', makes it possible to highlight parts of the user interface in a very dynamic manner. For instance, adding the following rule to the stylesheet above will given any {{DocLink|QLineEdit}} with the ''urgent'' property set to true red text on a yellow background.
  
 
<code>
 
<code>
[urgent=true] {
+
QLineEdit[urgent=true] {
color: red;
+
  color: red;
 
}
 
}
 
</code>
 
</code>
  
This does not have to be limited to QLineEdits though. Setting the ''urgent'' property to true on a {{DocLink|QCheckBox}} or QPushButton will make their texts show in red as well. Basically, any stylesheet aware widget can be turned red using this simple trick.
+
This does not have to be limited to QLineEdits though. if the selector was changed from <tt>QLineEdit[urgent=true]</tt> to <tt>[urgent=true]</tt>, setting the ''urgent'' property to true on a {{DocLink|QCheckBox}} or QPushButton will make their texts show in red as well. Basically, any stylesheet aware widget could be turned red using this generic selector.
  
 
== Limitations ==
 
== Limitations ==
  
There are however limitations to using this trick. The main one is, that the style will not update itself automatically when the value of the property changes. This limits the usefulness of this feature, as you can not simply trigger an update of the visual appearance of a widget by only changing a simple property that you referenced from the style sheet.
+
There are limitations to using this trick. The main one is that the style will not update itself automatically when the value of a property referenced from the style sheet changes. Instead, you must manually trigger an update of the visual appearance of a widget when a styled property changes. For example:
 
 
=== Note ===
 
 
 
While implementing dynamic properties we need to update the widget when the property changes, for example if we want to paint a frame with red color if there is an error. So we can set the stylesheet for the frame as
 
  
 
<code>
 
<code>
QFrame#TestDisplayFrame[error="true"]
+
myLineEdit->setProperty("urgent", true);
{
+
myLineEdit->style()->unpolish(myLineEdit);
background-color: red;
+
myLineEdit->style()->polish(myLineEdit);
border: 2px solid rgba(205, 92, 92, 255);
 
border-radius: 20px;
 
}
 
 
</code>
 
</code>
  
Then wherever we are changing the property we need to add the following code to trigger an update
+
Note that this must be done in the widget to which the style was applied. {{DocLink|qstyle|polish|QStyle::polish}} accepts either a QWidget or a QApplication as a parameter.
 
 
<code>
 
tstFrame->setProperty("error",true);
 
tstFrame->style()->unpolish(tstFrame);
 
tstFrame->style()->polish(tstFrame);
 
tstFrame->update();
 
</code>
 

Revision as of 19:12, 12 June 2016

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Introduction

Qt stylesheets make it possible to customize the look of Qt applications without having to master the magic behind Qt styles. From lighter tweaks to the quite complex, stylesheets can do the job. For a fully customized and unique user experience, QtQuick and QGraphicsView are a better choice.

When using stylesheets, styles are applied using selectors. For instance, the snippet below gives all QLineEdit widgets a yellow background color, if this style sheet is set on the form widget or on a widget that contains it. Here, the selector is the word QLineEdit:

QLineEdit
{
  background: yellow;
}

There are numerous selectors based on object names, sub-controls, pseudo-states and more. These can be used to change the look of a user interface and also make all QPushButton widgets named okButton have green text, and so on.

Custom properties

For dynamic changes in the user interface look, the property value selector can be used in combination with dynamic properties. Dynamic properties were introduced in Qt 4.2 and allow you to assign property values to QObjects for properties that do not exist at compile time. I.e. if you choose to set the a property called urgent to true for a QObject, that property will stick even tough the class does not contain a Q_PROPERTY macro for the property urgent.

Creating a stylesheet selector relying on a dynamic property, e.g. urgent, makes it possible to highlight parts of the user interface in a very dynamic manner. For instance, adding the following rule to the stylesheet above will given any QLineEdit with the urgent property set to true red text on a yellow background.

QLineEdit[urgent=true] {
  color: red;
}

This does not have to be limited to QLineEdits though. if the selector was changed from QLineEdit[urgent=true] to [urgent=true], setting the urgent property to true on a QCheckBox or QPushButton will make their texts show in red as well. Basically, any stylesheet aware widget could be turned red using this generic selector.

Limitations

There are limitations to using this trick. The main one is that the style will not update itself automatically when the value of a property referenced from the style sheet changes. Instead, you must manually trigger an update of the visual appearance of a widget when a styled property changes. For example:

myLineEdit->setProperty("urgent", true);
myLineEdit->style()->unpolish(myLineEdit);
myLineEdit->style()->polish(myLineEdit);

Note that this must be done in the widget to which the style was applied. QStyle::polish accepts either a QWidget or a QApplication as a parameter.