La sintaxis de las hojas de estilo
La terminología y las reglas sintácticas de las hojas de estilo de Qt son prácticamente idénticas a las de CSS para HTML. Si ya conoces CSS, probablemente puedas leer esta sección por encima rápidamente.
Reglas de estilo
Las hojas de estilo consisten en una secuencia de reglas de estilo. Una regla de estilo se compone de un selector y una declaración. El selector especifica a qué widgets afecta la regla; la declaración especifica qué propiedades deben establecerse en el widget. Por ejemplo:
QPushButton { color: red }En la regla de estilo anterior, « QPushButton » es el selector y « { color: red } » es la declaración. La regla especifica que « QPushButton » y sus subclases (por ejemplo, « MyPushButton ») deben utilizar el rojo como color de primer plano.
Las hojas de estilo de Qt no suelen distinguir entre mayúsculas y minúsculas (es decir, color, Color, COLOR y cOloR hacen referencia a la misma propiedad). Las únicas excepciones son los nombres de clase, object names, y los nombres de propiedades de Qt, que sí distinguen entre mayúsculas y minúsculas.
Se pueden especificar varios selectores para la misma declaración, separándolos con comas (,). Por ejemplo, la regla
QPushButton, QLineEdit, QComboBox { color: red }es equivalente a esta secuencia de tres reglas:
QPushButton { color: red }
QLineEdit { color: red }
QComboBox { color: red }La parte de declaración de una regla de estilo es una lista de property: value pares, entre llaves ({}) y separados por puntos y comas. Por ejemplo:
QPushButton { color: red; background-color: white }Consulta la sección «Lista de propiedades » más abajo para ver la lista de propiedades que ofrecen los Qt Widgets.
Tipos de selectores
Todos los ejemplos anteriores han utilizado el tipo de selector más sencillo: el selector de tipo. Las hojas de estilo de Qt admiten todos los selectores definidos en CSS2. La tabla siguiente resume los tipos de selectores más útiles.
| Selector | Ejemplo | Explicación |
|---|---|---|
| Selector universal | * | Coincide con todos los widgets. |
| Selector de tipo | QPushButton | Coincide con instancias de ` QPushButton ` y de sus subclases. |
| Selector de propiedad | QPushButton[flat="false"] | Coincide con instancias de ` QPushButton ` que no sean ` flat`. Puedes utilizar este selector para comprobar cualquier propiedad de Qt que admita ` QVariant::toString()` (consulta la documentación de la función ` toString()` para obtener más detalles). Además, se admite la propiedad especial ` class `, correspondiente al nombre de la clase.Este selector también se puede utilizar para comprobar propiedades dinámicas. Para obtener más información sobre la personalización mediante propiedades dinámicas, consulta «Personalización mediante propiedades dinámicas». En lugar de Advertencia: Si el valor de la propiedad Qt cambia después de haber establecido la hoja de estilos, podría ser necesario forzar un nuevo cálculo de la hoja de estilos. Una forma de hacerlo es desactivar la hoja de estilos y volver a activarla. |
| Selector de clases | .QPushButton | Coincide con instancias de QPushButton, pero no con las de sus subclases. Esto equivale a ` |
| Selector de ID de | QPushButton#okButton | Coincide con todas las instancias de ` QPushButton ` cuyo ` object name ` sea ` okButton`. |
| Selector de descendientes | QDialog QPushButton | Coincide con todas las instancias de QPushButton que sean descendientes (hijos, nietos, etc.) de un QDialog. |
| Selector de hijos | QDialog > QPushButton | Coincide con todas las instancias de QPushButton que sean hijos directos de un QDialog. |
Subcontroles
Para aplicar estilos a widgets complejos, es necesario acceder a los subcontroles del widget, como el botón desplegable de un « QComboBox » o las flechas arriba y abajo de un « QSpinBox ». Los selectores pueden contener subcontroles que permiten restringir la aplicación de una regla a subcontroles específicos del widget. Por ejemplo:
QComboBox::drop-down { image: url(dropdown.png) }La regla anterior aplica un estilo al botón desplegable de todos los QComboBox. Aunque la sintaxis de los dos puntos dobles (::) recuerda a los pseudoelementos de CSS3, los subcontroles de Qt difieren conceptualmente de estos y tienen una semántica de cascada diferente.
Los subcontroles siempre se posicionan con respecto a otro elemento: un elemento de referencia. Este elemento de referencia puede ser el widget u otro subcontrol. Por ejemplo, el ::drop-down de un QComboBox se coloca, por defecto, en la esquina superior derecha del rectángulo de relleno del QComboBox. El ::drop-down se coloca, por defecto, en el centro del rectángulo de «Contenido» del subcontrol ::drop-down. Consulta la «Lista de widgets personalizables» que figura a continuación para conocer los subcontroles que se pueden utilizar para aplicar estilos a un widget y sus posiciones por defecto.
El rectángulo de origen que se va a utilizar se puede modificar mediante la propiedad `subcontrol-origin`. Por ejemplo, si queremos colocar el menú desplegable en el rectángulo de margen ( QComboBox ) en lugar del rectángulo de relleno (Padding) predeterminado, podemos especificar:
La alineación del menú desplegable dentro del rectángulo de margen se modifica mediante la propiedad ` subcontrol-position `.
Las propiedades «width» y «height» se pueden utilizar para controlar el tamaño del subcontrol. Ten en cuenta que al establecer una imagen se define implícitamente el tamaño del subcontrol.
El esquema de posicionamiento relativo (position: relative) permite desplazar la posición del subcontrol respecto a su posición inicial. Por ejemplo, al pulsar el botón del menú desplegable de QComboBox, es posible que queramos que la flecha interior se desplace para dar un efecto de «pulsado». Para lograrlo, podemos especificar:
QComboBox::down-arrow {
image: url(down_arrow.png);
}
QComboBox::down-arrow:pressed {
position: relative;
top: 1px; left: 1px;
}El esquema de posicionamiento absoluto (position: absolute) permite modificar la posición y el tamaño del subcontrol con respecto al elemento de referencia.
Una vez posicionados, se tratan igual que los widgets y se les puede aplicar estilo utilizando el modelo de caja.
Consulte la «Lista de subcontroles» que aparece a continuación para ver los subcontroles compatibles, y el artículo «Personalización del subcontrol indicador de menú de QPushButton» para ver un ejemplo práctico.
Nota: En el caso de widgets complejos, como QComboBox y QScrollBar, si se personaliza una propiedad o un subcontrol, también deben personalizarse todas las demás propiedades o subcontroles.
Pseudoestados
Los selectores pueden contener pseudoestados que indican que la aplicación de la regla se restringe en función del estado del widget. Los pseudoestados aparecen al final del selector, separados por dos puntos (:). Por ejemplo, la siguiente regla se aplica cuando se pasa el ratón por encima de un QPushButton:
QPushButton:hover { color: white }Los pseudoestados pueden negarse utilizando el operador de exclamación. Por ejemplo, la siguiente regla se aplica cuando el ratón no se sitúa sobre un QRadioButton:
QRadioButton:!hover { color: red }Los pseudoestados se pueden encadenar, en cuyo caso se sobreentiende un «Y» lógico. Por ejemplo, la siguiente regla se aplica cuando el cursor pasa por encima de un « QCheckBox » marcado:
QCheckBox:hover:checked { color: white }Los pseudoestados negados pueden aparecer en cadenas de pseudoestados. Por ejemplo, la siguiente regla se aplica cuando se pasa el ratón por encima de un QPushButton que no está pulsado:
QPushButton:hover:!pressed { color: blue; }Si es necesario, el «O» lógico se puede expresar utilizando el operador de coma:
Los pseudoestados pueden aparecer en combinación con subcontroles. Por ejemplo:
QComboBox::drop-down:hover { image: url(dropdown_bright.png) }Consulta la sección «Lista de pseudoestados » más abajo para ver la lista de pseudoestados que ofrecen los Qt Widgets.
Resolución de conflictos
Los conflictos surgen cuando varias reglas de estilo especifican las mismas propiedades con valores diferentes. Consideremos la siguiente hoja de estilo:
QPushButton#okButton { color: gray }
QPushButton { color: red }Ambas reglas coinciden con instancias de ` QPushButton ` denominadas ` okButton ` y existe un conflicto en la propiedad ` color `. Para resolver este conflicto, debemos tener en cuenta la especificidad de los selectores. En el ejemplo anterior, ` QPushButton#okButton ` se considera más específico que ` QPushButton`, ya que (normalmente) hace referencia a un único objeto, y no a todas las instancias de una clase.
Del mismo modo, los selectores con pseudoestados son más específicos que aquellos que no especifican pseudoestados. Así, la siguiente hoja de estilo especifica que un QPushButton debe tener texto blanco cuando el ratón pasa por encima de él y, en caso contrario, texto rojo:
QPushButton:hover { color: white }
QPushButton { color: red }Aquí hay uno complicado:
QPushButton:hover { color: white }
QPushButton:enabled { color: red }En este caso, ambos selectores tienen la misma especificidad, por lo que, si se pasa el ratón por encima del botón mientras está activado, prevalece la segunda regla. Si queremos que el texto sea blanco en ese caso, podemos reordenar las reglas de la siguiente manera:
QPushButton:enabled { color: red }
QPushButton:hover { color: white }Como alternativa, podemos hacer que la primera regla sea más específica:
QPushButton:hover:enabled { color: white }
QPushButton:enabled { color: red }Se plantea un problema similar en relación con los selectores de tipo. Consideremos el siguiente ejemplo:
QPushButton { color: red }
QAbstractButton { color: gray }Ambas reglas se aplican a las instancias de « QPushButton » (ya que « QPushButton » hereda de « QAbstractButton ») y existe un conflicto en la propiedad «color ». Dado que « QPushButton » hereda de « QAbstractButton », podría resultar tentador suponer que « QPushButton » es más específico que « QAbstractButton ». Sin embargo, a efectos de los cálculos de la hoja de estilo, todos los selectores de tipo tienen la misma especificidad, y la regla que aparece en último lugar tiene prioridad. En otras palabras, el color se establece en gray para todos los QAbstractButton, incluidos los QPushButton. Si realmente queremos que los QPushButtontengan el texto en rojo, siempre podemos reordenar las reglas.
Para determinar la especificidad de una regla, las hojas de estilo de Qt siguen la especificación CSS2:
La especificidad de un selector se calcula de la siguiente manera:
- se cuenta el número de atributos ID en el selector (= a)
- se cuenta el número de otros atributos y pseudoclases del selector (= b)
- contar el número de nombres de elementos en el selector (= c)
- ignora los pseudoelementos [es decir, los subcontroles].
La concatenación de los tres números a-b-c (en un sistema numérico de base grande) da como resultado la especificidad.
Algunos ejemplos:
* {} /* a=0 b=0 c=0 -> specificity = 0 */ LI {} /* a=0 b=0 c=1 -> specificity = 1 */ UL LI {} /* a=0 b=0 c=2 -> specificity = 2 */ UL OL+LI {} /* a=0 b=0 c=3 -> specificity = 3 */ H1 + *[REL=up]{} /* a=0 b=1 c=1 -> specificity = 11 */ UL OL LI.red {} /* a=0 b=1 c=3 -> specificity = 13 */ LI.red.level {} /* a=0 b=2 c=1 -> specificity = 21 */ #x34y {} /* a=1 b=0 c=0 -> specificity = 100 */
Cascada
Las hojas de estilo se pueden aplicar al « QApplication », a los widgets padres y a los widgets hijos. La hoja de estilo efectiva de un widget cualquiera se obtiene fusionando las hojas de estilo aplicadas a sus antepasados (padre, abuelo, etc.), así como cualquier hoja de estilo aplicada al « QApplication ».
Cuando surgen conflictos, siempre se da preferencia a la hoja de estilo propia del widget frente a cualquier hoja de estilo heredada, independientemente de la especificidad de las reglas en conflicto. Del mismo modo, se da preferencia a la hoja de estilo del widget padre frente a la del abuelo, etc.
Una consecuencia de esto es que establecer una regla de estilo en un widget le otorga automáticamente prioridad sobre otras reglas especificadas en las hojas de estilo de los widgets antecesores o en la hoja de estilo QApplication. Consideremos el siguiente ejemplo. En primer lugar, establecemos una hoja de estilo en QApplication:
qApp->setStyleSheet("QPushButton { color: white }");A continuación, establecemos una hoja de estilos en un objeto ` QPushButton `:
myPushButton->setStyleSheet("* { color: blue }");La hoja de estilos aplicada al objeto ` QPushButton ` obliga a que el ` QPushButton ` (y cualquier widget secundario) tenga el texto en azul, a pesar de la regla más específica establecida por la hoja de estilos de toda la aplicación.
El resultado habría sido el mismo si hubiéramos escrito
myPushButton->setStyleSheet("color: blue");, salvo que, si el QPushButton tuviera elementos secundarios (lo cual es poco probable), la hoja de estilo no tendría ningún efecto sobre ellos.
La cascada de hojas de estilo es un tema complejo. Consulta la especificación CSS2 para conocer todos los detalles. Ten en cuenta que, actualmente, Qt no implementa el !important.
Herencia
En el CSS clásico, cuando no se establecen explícitamente la fuente y el color de un elemento, estos se heredan automáticamente del elemento padre. Por defecto, al utilizar las hojas de estilo de Qt, un widget no hereda automáticamente la configuración de fuente y color de su widget padre.
Por ejemplo, consideremos un ` QPushButton ` dentro de un ` QGroupBox`:
qApp->setStyleSheet("QGroupBox { color: red; } ");El QPushButton no tiene un color definido explícitamente. Por lo tanto, en lugar de heredar el color de su elemento padre QGroupBox, adopta el color del sistema. Si queremos establecer el color de un QGroupBox y de sus elementos hijos, podemos escribir:
qApp->setStyleSheet("QGroupBox, QGroupBox * { color: red; }");Por el contrario, al establecer una fuente y una paleta mediante ` QWidget::setFont()` y ` QWidget::setPalette()`, estos ajustes se propagan a los widgets hijos.
Si prefieres que la fuente y la paleta se propaguen a los widgets hijos, puedes establecer el indicador Qt::AA_UseStyleSheetPropagationInWidgetStyles, de la siguiente manera:
Uso:
QCoreApplication::setAttribute(Qt::AA_UseStyleSheetPropagationInWidgetStyles, true);Cuando se habilita la propagación de la fuente y la paleta de estilo del widget, los cambios en la fuente y la paleta realizados a través de las hojas de estilo de Qt se comportarán como si el usuario hubiera llamado manualmente a los métodos correspondientes ` QWidget::setPalette()` y ` QWidget::setFont()` en todos los `Qt Widgets` a los que se dirige la hoja de estilo.
- Los cambios realizados mediante una hoja de estilos se propagan. Se aplican a todos los widgets que coinciden con la hoja de estilos una sola vez, en el momento en que se realiza el cambio.
- Los cambios realizados al llamar a QWidget::setPalette() o QWidget::setFont() se heredan. Son heredados por todos los hijos existentes y futuros, en los que no se haya establecido explícitamente el pincel o la fuente correspondientes.
Widgets dentro de los espacios de nombres de C++
El selector de tipos se puede utilizar para aplicar estilos a widgets de un tipo concreto. Por ejemplo,
class MyPushButton : public QPushButton {
// ...
};
// ...
void someFunction()
{
qApp->setStyleSheet("MyPushButton { background: yellow; }");
//...La hoja de estilo de Qt utiliza QObject::className() del widget para determinar cuándo aplicar el selector de tipos. Cuando los widgets personalizados se encuentran dentro de espacios de nombres, QObject::className() devuelve <ESPACIO de nombres>::<NOMBRE de clase>. Esto entra en conflicto con la sintaxis de los subcontroles. Para solucionar este problema, al utilizar el selector de tipos para widgets dentro de espacios de nombres, debemos sustituir :: por --. Por ejemplo,
namespace ns {
class MyPushButton : public QPushButton {
// ...
};
}
// ...
void someMethod()
{
qApp->setStyleSheet("ns--MyPushButton { background: yellow; }");
//...Configuración de las propiedades de QObject
A partir de la versión 4.3, cualquier Q_PROPERTY que se pueda diseñar se puede configurar utilizando la sintaxis qproperty-<nombre de la propiedad>.
Por ejemplo,
MyLabel { qproperty-pixmap: url(pixmap.png); }
MyGroupBox { qproperty-titleColor: rgb(100, 200, 100); }
QPushButton { qproperty-iconSize: 20px 20px; }si la propiedad hace referencia a una enumeración declarada con ` Q_ENUM`, debes hacer referencia a sus constantes por su nombre, no por su valor numérico.
Nota: Utiliza la sintaxis `qproperty` con precaución, ya que modifica el widget que se está dibujando. Además, la sintaxis `qproperty` solo se evalúa una vez, concretamente cuando el estilo aplica los retoques finales al widget. Esto significa que cualquier intento de utilizarlas en pseudoestados como ` QPushButton:hover` no funcionará.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.