En esta página

Ejemplos de hojas de estilo de Qt

A continuación veremos algunos ejemplos para empezar a utilizar las hojas de estilo de Qt.

Uso de las hojas de estilo

Personalización de los colores de primer plano y de fondo

Empecemos por establecer el amarillo como color de fondo de todos los « QLineEdit» de una aplicación. Esto se puede conseguir así:

qApp->setStyleSheet("QLineEdit { background-color: yellow }");

Si queremos que la propiedad se aplique únicamente a los elementos ` QLineEdit` que sean hijos (o nietos o bisnietos) de un cuadro de diálogo específico, haríamos mejor lo siguiente:

myDialog->setStyleSheet("QLineEdit { background-color: yellow }");

Si queremos que la propiedad se aplique únicamente a un « QLineEdit » específico, podemos asignarle un nombre mediante ` QObject::setObjectName()` y utilizar un selector de ID para referirnos a él:

myDialog->setStyleSheet("QLineEdit#nameEdit { background-color: yellow }");

Como alternativa, podemos establecer la propiedad `background-color ` directamente en el ` QLineEdit`, omitiendo el selector:

nameEdit->setStyleSheet("background-color: yellow");

Para garantizar un buen contraste, también deberíamos especificar un color adecuado para el texto:

nameEdit->setStyleSheet("color: blue; background-color: yellow");

También podría ser una buena idea cambiar los colores utilizados para el texto seleccionado:

nameEdit->setStyleSheet("color: blue;"
                        "background-color: yellow;"
                        "selection-color: yellow;"
                        "selection-background-color: blue;");

Personalización mediante propiedades dinámicas

Hay muchas situaciones en las que necesitamos presentar un formulario que contenga campos obligatorios. Para indicar al usuario que el campo es obligatorio, una solución eficaz (aunque estéticamente cuestionable) es utilizar el amarillo como color de fondo para esos campos. Resulta que esto es muy fácil de implementar utilizando las hojas de estilo de Qt. En primer lugar, utilizaríamos la siguiente hoja de estilos para toda la aplicación:

*[mandatoryField="true"] { background-color: yellow }

Esto significa que todos los widgets cuya propiedad Qt « mandatoryField » esté establecida en «true» tendrían un fondo amarillo.

A continuación, para cada widget de campo obligatorio, simplemente crearíamos una propiedad ` mandatoryField ` sobre la marcha y la estableceríamos en `true`. Por ejemplo:

QLineEdit *nameEdit = new QLineEdit(this);
nameEdit->setProperty("mandatoryField", true);

QLineEdit *emailEdit = new QLineEdit(this);
emailEdit->setProperty("mandatoryField", true);

QSpinBox *ageSpinBox = new QSpinBox(this);
ageSpinBox->setProperty("mandatoryField", true);

Personalización de un QPushButton utilizando el modelo de caja

En esta ocasión, mostraremos cómo crear un QPushButton rojo. Este QPushButton probablemente estaría vinculado a un fragmento de código muy destructivo.

En un primer momento, nos sentiríamos tentados a utilizar esta hoja de estilo:

QPushButton#evilButton { background-color: red }

Sin embargo, el resultado es un botón aburrido y plano, sin bordes:

Botón rojo plano

Lo que ha ocurrido es lo siguiente:

  • Hemos realizado una solicitud que no se puede satisfacer utilizando únicamente los estilos nativos (por ejemplo, el motor de temas nativo de Windows no nos permite especificar el color de fondo de un botón).
  • Por lo tanto, el botón se representa utilizando hojas de estilo.
  • No hemos especificado ningún valor para «border-width» ni «border-style», por lo que, por defecto, obtenemos un borde de 0 píxeles de ancho con el estilo « none ».

Mejoremos la situación especificando un borde:

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-color: beige;
}

Botón rojo con un borde beige

Ya tiene mucho mejor aspecto. Pero el botón parece un poco apretado. Especifiquemos algo de espacio entre el borde y el texto utilizando el relleno (padding). Además, estableceremos un ancho mínimo, redondearemos las esquinas y especificaremos una fuente más grande para que el botón tenga un aspecto más agradable:

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-radius: 10px;
    border-color: beige;
    font: bold 14px;
    min-width: 10em;
    padding: 6px;
}

Botón rojo con un borde redondo de color beige y un texto grande y llamativo

El único problema que queda es que el botón no reacciona cuando lo pulsamos. Podemos solucionarlo especificando un color de fondo ligeramente diferente y utilizando un estilo de borde distinto.

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-radius: 10px;
    border-color: beige;
    font: bold 14px;
    min-width: 10em;
    padding: 6px;
}
QPushButton#evilButton:pressed {
    background-color: rgb(224, 0, 0);
    border-style: inset;
}

Personalización del subcontrol «Indicador de menú» del QPushButton

Los subcontroles permiten acceder a los subelementos de un widget. Por ejemplo, un QPushButton asociado a un menú (mediante QPushButton::setMenu()) tiene un indicador de menú. Personalicemos el indicador de menú del botón rojo:

QPushButton#evilButton::menu-indicator {
    image: url(myindicator.png);
}

Por defecto, el indicador de menú se encuentra en la esquina inferior derecha del rectángulo de relleno. Podemos cambiar esto especificando subcontrol-position y subcontrol-origin para anclar el indicador de otra manera. También podemos utilizar top y left para desplazar el indicador unos cuantos píxeles. Por ejemplo:

QPushButton::menu-indicator {
    image: url(myindicator.png);
    subcontrol-position: right center;
    subcontrol-origin: padding;
    left: -2px;
}

Esto coloca el « myindicator.png » en el centro a la derecha del rectángulo de relleno del « QPushButton » (véase «subcontrol-origin» para obtener más información).

Ejemplo de selector complejo

Dado que el rojo parece ser nuestro color favorito, hagamos que el texto del « QLineEdit » sea rojo configurando la siguiente hoja de estilos para toda la aplicación:

QLineEdit { color: red }

Sin embargo, nos gustaría indicar visualmente que un QLineEdit es de solo lectura haciéndolo aparecer en gris:

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }

En algún momento, nuestro equipo de diseño nos plantea el requisito de que todos los « QLineEdit» del formulario de registro (con la propiedad « object name » registrationDialog) sean de color marrón:

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }
#registrationDialog QLineEdit { color: brown }

Tras varias reuniones de diseño de la interfaz de usuario, decidimos que todos nuestros « QDialog» deben tener « QLineEdit» de color marrón:

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }
QDialog QLineEdit { color: brown }

Pregunta: ¿Qué ocurre si tenemos un « QLineEdit » de solo lectura dentro de un « QDialog »? [Pista: la sección «Resolución de conflictos» anterior explica qué ocurre en casos como este.]

Personalización de widgets específicos

Esta sección ofrece ejemplos para personalizar widgets específicos mediante hojas de estilo.

Personalización de QAbstractScrollArea

El fondo de cualquier QAbstractScrollArea (vistas de elementos, QTextEdit y QTextBrowser) se puede configurar mediante las propiedades de fondo. Por ejemplo, para establecer una imagen de fondo que se desplace junto con la barra de desplazamiento:

QTextEdit, QListView {
    background-color: white;
    background-image: url(draft.png);
    background-attachment: scroll;
}

Si se desea que la imagen de fondo quede fija con respecto a la ventana de visualización:

QTextEdit, QListView {
    background-color: white;
    background-image: url(draft.png);
    background-attachment: fixed;
}

Personalización de QCheckBox

La aplicación de estilos a un QCheckBox es casi idéntica a la de un QRadioButton. La principal diferencia es que un QCheckBox de tres estados tiene un estado indeterminado.

QCheckBox {
    spacing: 5px;
}

QCheckBox::indicator {
    width: 13px;
    height: 13px;
}

QCheckBox::indicator:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

QCheckBox::indicator:unchecked:hover {
    image: url(:/images/checkbox_unchecked_hover.png);
}

QCheckBox::indicator:unchecked:pressed {
    image: url(:/images/checkbox_unchecked_pressed.png);
}

QCheckBox::indicator:checked {
    image: url(:/images/checkbox_checked.png);
}

QCheckBox::indicator:checked:hover {
    image: url(:/images/checkbox_checked_hover.png);
}

QCheckBox::indicator:checked:pressed {
    image: url(:/images/checkbox_checked_pressed.png);
}

QCheckBox::indicator:indeterminate:hover {
    image: url(:/images/checkbox_indeterminate_hover.png);
}

QCheckBox::indicator:indeterminate:pressed {
    image: url(:/images/checkbox_indeterminate_pressed.png);
}

Personalización de QComboBox

Veremos un ejemplo en el que el botón desplegable de un QComboBox aparece «fusionado» con el marco del cuadro combinado.

QComboBox {
    border: 1px solid gray;
    border-radius: 3px;
    padding: 1px 18px 1px 3px;
    min-width: 6em;
}

QComboBox:editable {
    background: white;
}

QComboBox:!editable, QComboBox::drop-down:editable {
     background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                 stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                 stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
}

/* QComboBox gets the "on" state when the popup is open */
QComboBox:!editable:on, QComboBox::drop-down:editable:on {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #D3D3D3, stop: 0.4 #D8D8D8,
                                stop: 0.5 #DDDDDD, stop: 1.0 #E1E1E1);
}

QComboBox:on { /* shift the text when the popup opens */
    padding-top: 3px;
    padding-left: 4px;
}

QComboBox::drop-down {
    subcontrol-origin: padding;
    subcontrol-position: top right;
    width: 15px;

    border-left-width: 1px;
    border-left-color: darkgray;
    border-left-style: solid; /* just a single line */
    border-top-right-radius: 3px; /* same radius as the QComboBox */
    border-bottom-right-radius: 3px;
}

QComboBox::down-arrow {
    image: url(/usr/share/icons/crystalsvg/16x16/actions/1downarrow.png);
}

QComboBox::down-arrow:on { /* shift the arrow when popup is open */
    top: 1px;
    left: 1px;
}

El menú emergente del QComboBox es un QAbstractItemView y se personaliza mediante el selector de descendientes:

QComboBox QAbstractItemView {
    border: 2px solid darkgray;
    selection-background-color: lightgray;
}

Personalización de QDockWidget

La barra de título y los botones de un QDockWidget se pueden personalizar de la siguiente manera:

QDockWidget {
    border: 1px solid lightgray;
    titlebar-close-icon: url(close.png);
    titlebar-normal-icon: url(undock.png);
}

QDockWidget::title {
    text-align: left; /* align the text to the left */
    background: lightgray;
    padding-left: 5px;
}

QDockWidget::close-button, QDockWidget::float-button {
    border: 1px solid transparent;
    background: darkgray;
    padding: 0px;
}

QDockWidget::close-button:hover, QDockWidget::float-button:hover {
    background: gray;
}

QDockWidget::close-button:pressed, QDockWidget::float-button:pressed {
    padding: 1px -1px -1px 1px;
}

Si se desea desplazar los botones del widget de acoplamiento hacia la izquierda, se puede utilizar la siguiente hoja de estilo:

QDockWidget {
    border: 1px solid lightgray;
    titlebar-close-icon: url(close.png);
    titlebar-normal-icon: url(float.png);
}

QDockWidget::title {
    text-align: left;
    background: lightgray;
    padding-left: 35px;
}

QDockWidget::close-button, QDockWidget::float-button {
    background: darkgray;
    padding: 0px;
    icon-size: 14px; /* maximum icon size */
}

QDockWidget::close-button:hover, QDockWidget::float-button:hover {
    background: gray;
}

QDockWidget::close-button:pressed, QDockWidget::float-button:pressed {
    padding: 1px -1px -1px 1px;
}

QDockWidget::close-button {
    subcontrol-position: top left;
    subcontrol-origin: margin;
    position: absolute;
    top: 0px; left: 0px; bottom: 0px;
    width: 14px;
}

QDockWidget::float-button {
    subcontrol-position: top left;
    subcontrol-origin: margin;
    position: absolute;
    top: 0px; left: 16px; bottom: 0px;
    width: 14px;
}

Nota: Para personalizar el separador (controlador de tamaño) de una ventana « QDockWidget », utiliza QMainWindow::separator.

Personalización de QFrame

El estilo de un QFrame se define mediante el modelo de caja (Box Model).

QFrame, QLabel, QToolTip {
    border: 2px solid green;
    border-radius: 4px;
    padding: 2px;
    background-image: url(images/welcome.png);
}

Personalización de QGroupBox

Veamos un ejemplo en el que se centra el título del QGroupBox.

QGroupBox {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #E0E0E0, stop: 1 #FFFFFF);
    border: 2px solid gray;
    border-radius: 5px;
    margin-top: 1ex; /* leave space at the top for the title */
}

QGroupBox::title {
    subcontrol-origin: margin;
    subcontrol-position: top center; /* position at the top center */
    padding: 0 3px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #FF0ECE, stop: 1 #FFFFFF);
}

Para un QGroupBox con casillas de selección, utiliza el subcontrol {#indicator-sub}{::indicator} y aplícale el mismo estilo que a un QCheckBox (es decir)

QGroupBox::indicator {
    width: 13px;
    height: 13px;
}

QGroupBox::indicator:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

/* proceed with styling just like QCheckBox */

Personalización de QHeaderView

QHeaderView se personaliza de la siguiente manera:

QHeaderView::section {
    background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                                      stop:0 #616161, stop: 0.5 #505050,
                                      stop: 0.6 #434343, stop:1 #656565);
    color: white;
    padding-left: 4px;
    border: 1px solid #6c6c6c;
}

QHeaderView::section:checked
{
    background-color: red;
}

/* style the sort indicator */
QHeaderView::down-arrow {
    image: url(down_arrow.png);
}

QHeaderView::up-arrow {
    image: url(up_arrow.png);
}

Personalización de QLineEdit

El marco de un QLineEdit se diseña utilizando el modelo de caja (Box Model). Para crear un campo de edición de línea con esquinas redondeadas, podemos establecer:

QLineEdit {
    border: 2px solid gray;
    border-radius: 10px;
    padding: 0 8px;
    background: yellow;
    selection-background-color: darkgray;
}

El carácter de contraseña de los campos de edición de línea que tienen el modo de eco « QLineEdit::Password » se puede configurar utilizando:

QLineEdit[echoMode="2"] {
    lineedit-password-character: 9679;
}

El fondo de un QLineEdit de solo lectura se puede modificar como se indica a continuación:

QLineEdit:read-only {
    background: lightblue;
}

Personalización de QListView

El color de fondo de las filas alternas se puede personalizar utilizando la siguiente hoja de estilos:

QListView {
    alternate-background-color: yellow;
}

Para aplicar un fondo especial al pasar el cursor por encima de los elementos, podemos utilizar el subcontrol ::item. Por ejemplo,

QListView {
    show-decoration-selected: 1; /* make the selection span the entire width of the view */
}

QListView::item:alternate {
    background: #EEEEEE;
}

QListView::item:selected {
    border: 1px solid #6a6ea9;
}

QListView::item:selected:!active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #ABAFE5, stop: 1 #8588B2);
}

QListView::item:selected:active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #6a6ea9, stop: 1 #888dd9);
}

QListView::item:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #FAFBFE, stop: 1 #DCDEF1);
}

Personalización de QMainWindow

El separador de una QMainWindow se puede personalizar de la siguiente manera:

QMainWindow::separator {
    background: yellow;
    width: 10px; /* when vertical */
    height: 10px; /* when horizontal */
}

QMainWindow::separator:hover {
    background: red;
}

Personalización de QMenu

Los elementos individuales de un menú de opción ( QMenu ) se personalizan mediante el subcontrol «item» de la siguiente manera:

QMenu {
    background-color: #ABABAB; /* sets background of the menu */
    border: 1px solid black;
}

QMenu::item {
    /* sets background of menu item. set this to something non-transparent
        if you want menu color and menu item color to be different */
    background-color: transparent;
}

QMenu::item:selected { /* when user selects item using mouse or keyboard */
    background-color: #654321;
}

Para una personalización más avanzada, utiliza una hoja de estilos de la siguiente manera:

QMenu {
    background-color: white;
    margin: 2px; /* some spacing around the menu */
}

QMenu::item {
    padding: 2px 25px 2px 20px;
    border: 1px solid transparent; /* reserve space for selection border */
}

QMenu::item:selected {
    border-color: darkblue;
    background: rgba(100, 100, 100, 150);
}

QMenu::icon:checked { /* appearance of a 'checked' icon */
    background: gray;
    border: 1px inset gray;
    position: absolute;
    top: 1px;
    right: 1px;
    bottom: 1px;
    left: 1px;
}

QMenu::separator {
    height: 2px;
    background: lightblue;
    margin-left: 10px;
    margin-right: 5px;
}

QMenu::indicator {
    width: 13px;
    height: 13px;
}

/* non-exclusive indicator = check box style indicator (see QActionGroup::setExclusive) */
QMenu::indicator:non-exclusive:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

QMenu::indicator:non-exclusive:unchecked:selected {
    image: url(:/images/checkbox_unchecked_hover.png);
}

QMenu::indicator:non-exclusive:checked {
    image: url(:/images/checkbox_checked.png);
}

QMenu::indicator:non-exclusive:checked:selected {
    image: url(:/images/checkbox_checked_hover.png);
}

/* exclusive indicator = radio button style indicator (see QActionGroup::setExclusive) */
QMenu::indicator:exclusive:unchecked {
    image: url(:/images/radiobutton_unchecked.png);
}

QMenu::indicator:exclusive:unchecked:selected {
    image: url(:/images/radiobutton_unchecked_hover.png);
}

QMenu::indicator:exclusive:checked {
    image: url(:/images/radiobutton_checked.png);
}

QMenu::indicator:exclusive:checked:selected {
    image: url(:/images/radiobutton_checked_hover.png);
}

Personalización de QMenuBar

QMenuBar se personaliza de la siguiente manera:

QMenuBar {
    background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                                      stop:0 lightgray, stop:1 darkgray);
    spacing: 3px; /* spacing between menu bar items */
}

QMenuBar::item {
    padding: 1px 4px;
    background: transparent;
    border-radius: 4px;
}

QMenuBar::item:selected { /* when selected using mouse or keyboard */
    background: #a8a8a8;
}

QMenuBar::item:pressed {
    background: #888888;
}

Personalización de QProgressBar

El borde, el segmento y la alineación del texto de la barra de menú de calidad ( QProgressBar) se pueden personalizar mediante hojas de estilo. Sin embargo, si se personaliza una propiedad o un subcontrol, también deben personalizarse todas las demás propiedades o subcontroles.

Barra de progreso que muestra un 30 %

Por ejemplo, cambiamos el borde a gris y el segmento a cerúleo.

QProgressBar {
    border: 2px solid grey;
    border-radius: 5px;
}

QProgressBar::chunk {
    background-color: #05B8CC;
    width: 20px;
}

Esto nos deja la alineación del texto, que personalizamos colocando el texto en el centro de la barra de progreso.

QProgressBar {
    border: 2px solid grey;
    border-radius: 5px;
    text-align: center;
}

Se puede incluir un margen para que los fragmentos sean más visibles.

Barra de progreso con marcas

En la captura de pantalla anterior, utilizamos un margen de 0,5 píxeles.

QProgressBar::chunk {
    background-color: #CD96CD;
    width: 10px;
    margin: 0.5px;
}

Personalización de QPushButton

Un « QPushButton » se personaliza de la siguiente manera:

QPushButton {
    border: 2px solid #8f8f91;
    border-radius: 6px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #f6f7fa, stop: 1 #dadbde);
    min-width: 80px;
}

QPushButton:pressed {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

QPushButton:flat {
    border: none; /* no border for a flat push button */
}

QPushButton:default {
    border-color: navy; /* make the default button prominent */
}

Para un « QPushButton » con menú, utiliza el subcontrol «:: menu-indicator ».

QPushButton:open { /* when the button has its menu open */
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

QPushButton::menu-indicator {
    image: url(menu_indicator.png);
    subcontrol-origin: padding;
    subcontrol-position: bottom right;
}

QPushButton::menu-indicator:pressed, QPushButton::menu-indicator:open {
    position: relative;
    top: 2px; left: 2px; /* shift the arrow by 2 px */
}

Los botones « QPushButton » marcables tienen establecido el pseudoestado :checked.

Personalización de QRadioButton

El indicador de un QRadioButton se puede modificar utilizando:

QRadioButton::indicator {
    width: 13px;
    height: 13px;
}

QRadioButton::indicator::unchecked {
    image: url(:/images/radiobutton_unchecked.png);
}

QRadioButton::indicator:unchecked:hover {
    image: url(:/images/radiobutton_unchecked_hover.png);
}

QRadioButton::indicator:unchecked:pressed {
    image: url(:/images/radiobutton_unchecked_pressed.png);
}

QRadioButton::indicator::checked {
    image: url(:/images/radiobutton_checked.png);
}

QRadioButton::indicator:checked:hover {
    image: url(:/images/radiobutton_checked_hover.png);
}

QRadioButton::indicator:checked:pressed {
    image: url(:/images/radiobutton_checked_pressed.png);
}

Personalización de QScrollBar

El QScrollBar se puede personalizar utilizando sus subcontroles, como el controlador, la línea de adición, la sublínea, etc. Ten en cuenta que, si se personaliza una propiedad o un subcontrol, también deben personalizarse todas las demás propiedades o subcontroles.

Barra de desplazamiento verde estilizada

La barra de desplazamiento anterior se ha diseñado en color aguamarina con un borde gris liso.

QScrollBar:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    height: 15px;
    margin: 0px 20px 0 20px;
}
QScrollBar::handle:horizontal {
    background: white;
    min-width: 20px;
}
QScrollBar::add-line:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    width: 20px;
    subcontrol-position: right;
    subcontrol-origin: margin;
}

QScrollBar::sub-line:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    width: 20px;
    subcontrol-position: left;
    subcontrol-origin: margin;
}

Las flechas de izquierda y derecha tienen un borde gris sólido con fondo blanco. Como alternativa, también se puede incrustar la imagen de una flecha.

QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal {
    border: 2px solid grey;
    width: 3px;
    height: 3px;
    background: white;
}

QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal {
    background: none;
}

Si quieres que los botones de desplazamiento de la barra de desplazamiento se coloquen juntos (en lugar de en los extremos), como en macOS, puedes utilizar la siguiente hoja de estilos:

QScrollBar:horizontal {
    border: 2px solid green;
    background: cyan;
    height: 15px;
    margin: 0px 40px 0 0px;
}

QScrollBar::handle:horizontal {
    background: gray;
    min-width: 20px;
}

QScrollBar::add-line:horizontal {
    background: blue;
    width: 16px;
    subcontrol-position: right;
    subcontrol-origin: margin;
    border: 2px solid black;
}

QScrollBar::sub-line:horizontal {
    background: magenta;
    width: 16px;
    subcontrol-position: top right;
    subcontrol-origin: margin;
    border: 2px solid black;
    position: absolute;
    right: 20px;
}

QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal {
    width: 3px;
    height: 3px;
    background: pink;
}

QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal {
    background: none;
}

La barra de desplazamiento que utiliza la hoja de estilos anterior tiene este aspecto:

Barra de desplazamiento en color

Para personalizar una barra de desplazamiento vertical, utiliza una hoja de estilos similar a la siguiente:

 QScrollBar:vertical {
     border: 2px solid grey;
     background: #32CC99;
     width: 15px;
     margin: 22px 0 22px 0;
 }
 QScrollBar::handle:vertical {
     background: white;
     min-height: 20px;
 }
 QScrollBar::add-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: bottom;
     subcontrol-origin: margin;
 }

 QScrollBar::sub-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: top;
     subcontrol-origin: margin;
 }
 QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {
     border: 2px solid grey;
     width: 3px;
     height: 3px;
     background: white;
 }

 QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {
     background: none;
 }

Personalización de QSizeGrip

QSizeGrip suele personalizarse simplemente estableciendo una imagen.

QSizeGrip {
    image: url(:/images/sizegrip.png);
    width: 16px;
    height: 16px;
}

Personalización de QSlider

Puedes aplicar estilos al control deslizante horizontal como se indica a continuación:

QSlider::groove:horizontal {
    border: 1px solid #999999;
    height: 8px; /* the groove expands to the size of the slider by default. by giving it a height, it has a fixed size */
    background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #B1B1B1, stop:1 #c4c4c4);
    margin: 2px 0;
}

QSlider::handle:horizontal {
    background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #b4b4b4, stop:1 #8f8f8f);
    border: 1px solid #5c5c5c;
    width: 18px;
    margin: -2px 0; /* handle is placed by default on the contents rect of the groove. Expand outside the groove */
    border-radius: 3px;
}

Si desea cambiar el color de las partes del control deslizante situadas antes y después del controlador, puede utilizar los subcontroles «add-page» y «sub-page». Por ejemplo, para un control deslizante vertical:

QSlider::groove:vertical {
    background: red;
    position: absolute; /* absolutely position 4px from the left and right of the widget. setting margins on the widget should work too... */
    left: 4px; right: 4px;
}

QSlider::handle:vertical {
    height: 10px;
    background: green;
    margin: 0 -4px; /* expand outside the groove */
}

QSlider::add-page:vertical {
    background: white;
}

QSlider::sub-page:vertical {
    background: pink;
}

Personalización de QSpinBox

QSpinBox Se puede personalizar completamente como se muestra a continuación (la hoja de estilo incluye comentarios en línea):

QSpinBox {
    padding-right: 15px; /* make room for the arrows */
    border-image: url(:/images/frame.png) 4;
    border-width: 3;
}

QSpinBox::up-button {
    subcontrol-origin: border;
    subcontrol-position: top right; /* position at the top right corner */

    width: 16px; /* 16 + 2*1px border-width = 15px padding + 3px parent border */
    border-image: url(:/images/spinup.png) 1;
    border-width: 1px;
}

QSpinBox::up-button:hover {
    border-image: url(:/images/spinup_hover.png) 1;
}

QSpinBox::up-button:pressed {
    border-image: url(:/images/spinup_pressed.png) 1;
}

QSpinBox::up-arrow {
    image: url(:/images/up_arrow.png);
    width: 7px;
    height: 7px;
}

QSpinBox::up-arrow:disabled, QSpinBox::up-arrow:off { /* off state when value is max */
   image: url(:/images/up_arrow_disabled.png);
}

QSpinBox::down-button {
    subcontrol-origin: border;
    subcontrol-position: bottom right; /* position at bottom right corner */

    width: 16px;
    border-image: url(:/images/spindown.png) 1;
    border-width: 1px;
    border-top-width: 0;
}

QSpinBox::down-button:hover {
    border-image: url(:/images/spindown_hover.png) 1;
}

QSpinBox::down-button:pressed {
    border-image: url(:/images/spindown_pressed.png) 1;
}

QSpinBox::down-arrow {
    image: url(:/images/down_arrow.png);
    width: 7px;
    height: 7px;
}

QSpinBox::down-arrow:disabled,
QSpinBox::down-arrow:off { /* off state when value in min */
   image: url(:/images/down_arrow_disabled.png);
}

Personalización de QSplitter

Un ` QSplitter ` deriva de un ` QFrame ` y, por lo tanto, se puede diseñar como un ` QFrame`. El controlador o «handle» se personaliza utilizando el subcontrol `::handle`.

QSplitter::handle {
    image: url(images/splitter.png);
}

QSplitter::handle:horizontal {
    width: 2px;
}

QSplitter::handle:vertical {
    height: 2px;
}

QSplitter::handle:pressed {
    url(images/splitter_pressed.png);
}

Personalización de QStatusBar

Podemos establecer un fondo para la barra de estado y un borde para los elementos que contiene de la siguiente manera:

QStatusBar {
    background: brown;
}

QStatusBar::item {
    border: 1px solid red;
    border-radius: 3px;
}

Ten en cuenta que los widgets que se han añadido a la QStatusBar se pueden personalizar mediante la declaración de descendientes (es decir)

QStatusBar QLabel {
    border: 3px solid white;
}

Personalización de QTabWidget y QTabBar

Imagen de varias pestañas

Para la captura de pantalla anterior, necesitamos una hoja de estilos como la siguiente:

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
}

QTabWidget::tab-bar {
    left: 5px; /* move to the right by 5px */
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

QTabBar::tab:!selected {
    margin-top: 2px; /* make non-selected tabs look smaller */
}

A menudo necesitamos que las pestañas se superpongan para que tengan el aspecto que se muestra a continuación:

Imagen de pestañas superpuestas

Para que un widget de pestaña tenga el aspecto anterior, utilizamos márgenes negativos. Los valores negativos acercan el elemento a sus vecinos más de lo que lo estarían por defecto. La hoja de estilos resultante tiene este aspecto:

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
}

QTabWidget::tab-bar {
    left: 5px; /* move to the right by 5px */
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

QTabBar::tab:!selected {
    margin-top: 2px; /* make non-selected tabs look smaller */
}

/* make use of negative margins for overlapping tabs */
QTabBar::tab:selected {
    /* expand/overlap to the left and right by 4px */
    margin-left: -4px;
    margin-right: -4px;
}

QTabBar::tab:first:selected {
    margin-left: 0; /* the first selected tab has nothing to overlap with on the left */
}

QTabBar::tab:last:selected {
    margin-right: 0; /* the last selected tab has nothing to overlap with on the right */
}

QTabBar::tab:only-one {
    margin: 0; /* if there is only one tab, we don't want overlapping margins */
}

Para centrar la barra de pestañas (como se muestra a continuación), necesitamos la siguiente hoja de estilos:

Varias pestañas centradas en el widget

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
    position: absolute;
    top: -0.5em;
}

QTabWidget::tab-bar {
    alignment: center;
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

El indicador de desgarro y los botones de desplazamiento se pueden personalizar aún más de la siguiente manera:

QTabBar::tear {
    image: url(tear_indicator.png);
}

QTabBar::scroller { /* the width of the scroll buttons */
    width: 20px;
}

QTabBar QToolButton { /* the scroll buttons are tool buttons */
    border-image: url(scrollbutton.png) 2;
    border-width: 2px;
}

QTabBar QToolButton::right-arrow { /* the arrow mark in the tool buttons */
    image: url(rightarrow.png);
}

QTabBar QToolButton::left-arrow {
    image: url(leftarrow.png);
}

Puedes personalizar el botón de cierre de la siguiente manera:

QTabBar::close-button {
    image: url(close.png)
    subcontrol-position: left;
}
QTabBar::close-button:hover {
    image: url(close-hover.png)
}

Personalización de QTableView

Supongamos que queremos que el elemento seleccionado en un QTableView tenga como fondo un color rosa chicle que se desvanezca hacia el blanco.

Vista de tabla con estilo personalizado

Esto es posible con la propiedad «selection-background-color» y la sintaxis necesaria es:

QTableView {
    selection-background-color: qlineargradient(x1: 0, y1: 0, x2: 0.5, y2: 0.5,
                                stop: 0 #FF92BB, stop: 1 white);
}

El widget de esquina se puede personalizar utilizando la siguiente hoja de estilo

QTableView QTableCornerButton::section {
    background: red;
    border: 2px outset red;
}

El indicador de casilla de selección de QTableView también se puede personalizar. En el siguiente fragmento de código se personaliza el indicador background-color en estado desmarcado:

QTableView::indicator:unchecked {
    background-color: #d7d6d5
}

Personalización de QToolBar

El fondo y el controlador de una barra de herramientas ( QToolBar ) se personalizan como se muestra a continuación:

QToolBar {
    background: red;
    spacing: 3px; /* spacing between items in the tool bar */
}

QToolBar::handle {
    image: url(handle.png);
}

Personalización de QToolBox

Las pestañas de la barra de herramientas ( QToolBox ) se personalizan mediante el subcontrol «tab».

QToolBox::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border-radius: 5px;
    color: darkgray;
}

QToolBox::tab:selected { /* italicize selected tabs */
    font: italic;
    color: white;
}

Personalización de QToolButton

Existen tres tipos de QToolButtons.

QToolButton { /* all types of tool button */
    border: 2px solid #8f8f91;
    border-radius: 6px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #f6f7fa, stop: 1 #dadbde);
}

QToolButton[popupMode="1"] { /* only for MenuButtonPopup */
    padding-right: 20px; /* make way for the popup button */
}

QToolButton:pressed {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

/* the subcontrols below are used only in the MenuButtonPopup mode */
QToolButton::menu-button {
    border: 2px solid gray;
    border-top-right-radius: 6px;
    border-bottom-right-radius: 6px;
    /* 16px width + 4px for border = 20px allocated above */
    width: 16px;
}

QToolButton::menu-arrow {
    image: url(downarrow.png);
}

QToolButton::menu-arrow:open {
    top: 1px; left: 1px; /* shift it a bit */
}

Personalización de QToolTip

QToolTip se personaliza exactamente igual que un « QLabel ». Además, en las plataformas que lo admiten, se puede establecer la propiedad «opacity» para ajustar la opacidad.

Por ejemplo,

QToolTip {
    border: 2px solid darkkhaki;
    padding: 5px;
    border-radius: 3px;
    opacity: 200;
}

Personalización de QTreeView

El color de fondo de las filas alternas se puede personalizar utilizando la siguiente hoja de estilos:

QTreeView {
    alternate-background-color: yellow;
}

Para proporcionar un fondo especial al pasar el cursor por encima de los elementos, podemos utilizar el subcontrol ::item. Por ejemplo,

QTreeView {
    show-decoration-selected: 1;
}

QTreeView::item {
     border: 1px solid #d9d9d9;
    border-top-color: transparent;
    border-bottom-color: transparent;
}

QTreeView::item:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #e7effd, stop: 1 #cbdaf1);
    border: 1px solid #bfcde4;
}

QTreeView::item:selected {
    border: 1px solid #567dbc;
}

QTreeView::item:selected:active{
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6ea1f1, stop: 1 #567dbc);
}

QTreeView::item:selected:!active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6b9be8, stop: 1 #577fbf);
}

Las ramas de un QTreeView se diseñan mediante el subcontrol ::branch. La siguiente hoja de estilo asigna colores a los distintos estados al dibujar una rama.

QTreeView::branch {
        background: palette(base);
}

QTreeView::branch:has-siblings:!adjoins-item {
        background: cyan;
}

QTreeView::branch:has-siblings:adjoins-item {
        background: red;
}

QTreeView::branch:!has-children:!has-siblings:adjoins-item {
        background: blue;
}

QTreeView::branch:closed:has-children:has-siblings {
        background: pink;
}

QTreeView::branch:has-children:!has-siblings:closed {
        background: gray;
}

QTreeView::branch:open:has-children:has-siblings {
        background: magenta;
}

QTreeView::branch:open:has-children:!has-siblings {
        background: green;
}

Aunque resulte muy colorido, se puede crear un ejemplo más útil utilizando las siguientes imágenes:

Línea verticalLínea de unión para listasLínea para dar por terminada la listaFlecha que apunta a la derechaFlecha que apunta hacia abajo
vline.pngbranch-more.pngbranch-end.pngbranch-closed.pngbranch-open.png
QTreeView::branch:has-siblings:!adjoins-item {
    border-image: url(vline.png) 0;
}

QTreeView::branch:has-siblings:adjoins-item {
    border-image: url(branch-more.png) 0;
}

QTreeView::branch:!has-children:!has-siblings:adjoins-item {
    border-image: url(branch-end.png) 0;
}

QTreeView::branch:has-children:!has-siblings:closed,
QTreeView::branch:closed:has-children:has-siblings {
        border-image: none;
        image: url(branch-closed.png);
}

QTreeView::branch:open:has-children:!has-siblings,
QTreeView::branch:open:has-children:has-siblings  {
        border-image: none;
        image: url(branch-open.png);
}

La vista de árbol resultante tiene este aspecto:

Vista de árbol con ramas con estilo

Errores comunes

En esta sección se enumeran algunos errores comunes al utilizar hojas de estilo.

QPushButton e imágenes

Al aplicar estilos a un QPushButton, a menudo resulta conveniente utilizar una imagen como gráfico del botón. Es habitual probar la propiedad background-image, pero esto presenta una serie de inconvenientes: por ejemplo, el fondo suele quedar oculto tras la decoración del botón, ya que no se considera un fondo. Además, si se cambia el tamaño del botón, todo el fondo se estirará o se repetirá, lo que no siempre queda bien.

Es mejor utilizar la propiedad `border-image`, ya que siempre mostrará la imagen, independientemente del fondo (se puede combinar con un fondo si este contiene valores alfa), y cuenta con ajustes especiales para gestionar el cambio de tamaño del botón.

Fíjate en el siguiente fragmento de código:

        QPushButton {
            color: grey;
            border-image: url(/home/kamlie/code/button.png) 3 10 3 10;
            border-top: 3px transparent;
            border-bottom: 3px transparent;
            border-right: 10px transparent;
            border-left: 10px transparent;
        }

Esto generará un botón con este aspecto:

Botón con fondo

Los números que siguen a la URL indican el número de píxeles en la parte superior, derecha, inferior e izquierda, respectivamente. Estos números corresponden al borde y no deben estirarse cuando cambia el tamaño. Cada vez que cambies el tamaño del botón, la parte central de la imagen se estirará en ambas direcciones, mientras que los píxeles especificados en la hoja de estilos no lo harán. Esto hace que los bordes del botón tengan un aspecto más natural, como se ve aquí:

Botón con tamaños de borde especificados

Con bordes

Botón sin tamaños de borde especificados

Sin bordes

Véase también «Enfoques de estilo»en Qt Widgets, «Subconjunto de HTML compatible» y QStyle.

© 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.