Hojas de estilo de referencia Gestión del diseño

Ejemplos de Hojas de Estilo Qt

A continuación veremos algunos ejemplos para empezar a utilizar las Hojas de Estilo Qt.

Uso de las Hojas de Estilo

Personalizando los Colores de Primer Plano y Fondo

Comencemos estableciendo el amarillo como el color de fondo de todos los QLineEdits en una aplicación. Esto podría lograrse así:

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

Si queremos que la propiedad se aplique sólo a los QLineEdits que sean hijos (o nietos o bisnietos) de un cuadro de diálogo concreto, mejor así:

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

Si queremos que la propiedad se aplique sólo a un QLineEdit específico, podemos darle un nombre utilizando QObject::setObjectName() y utilizar un Selector ID para referirnos a él:

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

Alternativamente, podemos establecer la propiedad background-color directamente en QLineEdit, omitiendo el selector:

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

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

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

Puede ser una buena idea cambiar también 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 tiene campos obligatorios. Para indicar al usuario que el campo es obligatorio, una solución eficaz (aunque estéticamente dudosa) es utilizar el amarillo como color de fondo para esos campos. Resulta que esto es muy fácil de implementar usando Hojas de Estilo Qt. En primer lugar, utilizaríamos la siguiente hoja de estilo para toda la aplicación:

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

Esto significa que cada widget cuya propiedad mandatoryField Qt esté establecida a true tendría un fondo amarillo.

Luego, para cada widget de campo obligatorio, simplemente crearíamos una propiedad mandatoryField sobre la marcha y la pondríamos a 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);

Personalizando un QPushButton Usando el Modelo de Caja

Esta vez, mostraremos como crear un QPushButton rojo. Este QPushButton estaría presumiblemente conectado a una pieza de código muy destructiva.

Primero, estamos tentados a usar esta hoja de estilo:

QPushButton#evilButton { background-color: red }

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

Botón rojo plano

Lo que ha pasado es lo siguiente:

Hemos hecho una petición que no puede satisfacerse usando sólo los estilos nativos (por ejemplo, el motor de temas de Windows Vista no nos permite especificar el color de fondo de un botón).
Por lo tanto, el botón se renderiza utilizando hojas de estilo.
No hemos especificado ningún valor para border-width y border-style, así que por defecto obtenemos un borde de 0 píxeles de ancho del 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 borde beige

Las cosas ya se ven mucho mejor. Pero el botón parece un poco estrecho. Especifiquemos algo de espacio entre el borde y el texto utilizando el relleno. Además, aplicaremos una anchura mínima, 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 borde redondo beige y texto grande en negrita

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

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;
}

Los subcontroles dan acceso a los subelementos de un widget. Por ejemplo, un QPushButton asociado a un menú (usando QPushButton::setMenu()) tiene un indicador de menú. Vamos a personalizar el indicador de menú para el pulsador rojo:

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

Por defecto, el indicador de menú está situado en la esquina inferior derecha del rectángulo de relleno. Podemos cambiar esto especificando subcontrol-position y subcontrol-origin para anclar el indicador de forma diferente. También podemos utilizar top e left para mover el indicador unos píxeles. Por ejemplo:

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

Esto posiciona el myindicator.png en el centro a la derecha del rectángulo de relleno de QPushButton(ver subcontrol-origen para más información).

Ejemplo de selector complejo

Como el rojo parece ser nuestro color favorito, hagamos que el texto en QLineEdit sea rojo estableciendo la siguiente hoja de estilos para toda la aplicación:

QLineEdit { color: red }

Sin embargo, nos gustaría dar una indicación visual de que QLineEdit es de sólo lectura haciendo que aparezca en gris:

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

En algún momento, nuestro equipo de diseño llega con el requisito de que todos los QLineEdits del formulario de registro (con el object name registrationDialog ) sean de color marrón:

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

Unas cuantas reuniones de diseño de interfaz de usuario más tarde, decidimos que todos nuestros QDialogs deben tener QLineEdits de color marrón:

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

Cuestionario: ¿Qué ocurre si tenemos un QLineEdit de sólo lectura en un QDialog? [Sugerencia: La sección anterior Resolución de conflictos explica lo que ocurre en casos como éste].

Personalización de widgets específicos

Esta sección provee ejemplos para personalizar widgets específicos usando Hojas de Estilo.

Personalizando QAbstractScrollArea

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

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

Si la imagen de fondo debe fijarse con la ventana gráfica:

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

Personalizando QCheckBox

Estilizar un QCheckBox es casi idéntico a estilizar un QRadioButton. La principal diferencia es que un QCheckBox tristate 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 desplegable del QComboBox es un QAbstractItemView y se le aplica estilo utilizando el selector descendiente:

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

Personalizando QDockWidget

La barra de título y los botones de un QDockWidget pueden personalizarse 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 mover los botones del widget dock a 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 (manejador de redimensionamiento) de un QDockWidget, utilice QMainWindow::separator.

Personalización de QFrame

A QFrame se le da estilo utilizando el modelo The Box.

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

Personalizando QGroupBox

Veamos un ejemplo que mueve el título de QGroupBox al centro.

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 controlable, utilice el {#indicator-sub}{::indicator} subcontrol y aplíquele 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);
}

Personalizar QLineEdit

El marco de un QLineEdit se estiliza utilizando el Modelo de Caja. Para crear una 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 las ediciones de línea que tienen el modo de eco QLineEdit::Password puede establecerse utilizando:

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

El fondo de un QLineEdit de sólo lectura puede modificarse como se indica a continuación:

QLineEdit:read-only {
    background: lightblue;
}

Personalizando QListView

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

QListView {
    alternate-background-color: yellow;
}

Para proporcionar un fondo especial cuando se pasa el ratón 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);
}

Personalizando QMainWindow

El separador de un QMainWindow puede ser estilizado como sigue:

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

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

Personalizando QMenu

Los elementos individuales de un QMenu se estilizan usando 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, utilice una hoja de estilo como se indica a continuación:

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 tiene el siguiente estilo:

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 trozo y la alineación del texto de QProgressBar pueden personalizarse utilizando hojas de estilo. Sin embargo, si se personaliza una propiedad o subcontrol, todas las demás propiedades o subcontroles deben personalizarse también.

Barra de progreso del 30%.

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

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

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

Esto deja el texto-align, que personalizamos posicionando 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 obtener trozos más visibles.

Barra de progreso con muescas

En la captura de pantalla de arriba, usamos un margen de 0.5 píxeles.

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

Personalizando QPushButton

Un QPushButton tiene el siguiente estilo:

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ú, usa 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 QPushButton controlables tienen el pseudoestado :checked.

Personalización de QRadioButton

El indicador de un QRadioButton puede cambiarse 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 puede ser estilizado usando sus subcontroles como handle, add-line, sub-line, etc. Tenga en cuenta que si se personaliza una propiedad o subcontrol, todas las demás propiedades o subcontroles deben personalizarse también.

Barra de desplazamiento estilizada de color verde

La barra de desplazamiento de arriba tiene un estilo aguamarina con un borde gris sólido.

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 izquierda y derecha tienen un borde gris sólido con fondo blanco. Como alternativa, también 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 desea que los botones de desplazamiento de la barra de desplazamiento se coloquen juntos (en lugar de los bordes) como en macOS, puede 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 utilizando la hoja de estilos anterior tiene este aspecto:

Barra de desplazamiento coloreada

Para personalizar una barra de desplazamiento vertical utilice una hoja de estilo 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;
 }

La personalización de QSizeGrip

QSizeGrip normalmente se personaliza con una imagen.

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

Personalizando QSlider

Puede personalizar el deslizador horizontal como se muestra 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 deslizador antes y después de la manija, puede utilizar los subcontroles add-page y sub-page. Por ejemplo, para un deslizador 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 puede personalizarse completamente como se indica a continuación (la hoja de estilo tiene comentarios inline):

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 puede ser estilizado como un QFrame. El agarre o la manija se personaliza usando 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);
}

Personalizar QStatusBar

Podemos proporcionar un fondo para la barra de estado y un borde para los elementos dentro de la barra de estado de la siguiente manera:

QStatusBar {
    background: brown;
}

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

Ten en cuenta que los widgets que han sido añadidos a QStatusBar pueden ser estilizados usando la declaración descendiente (i.e)

QStatusBar QLabel {
    border: 3px solid white;
}

Personalizando 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 requerimos que las pestañas se superpongan para que se vean como abajo:

Imagen de pestañas superpuestas

Para un widget de pestaña como el de arriba, hacemos uso de márgenes negativos. Los valores negativos acercan el elemento a sus vecinos más de lo que estaría por defecto. La hoja de estilo 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 mover la barra de pestañas al centro (como abajo), necesitamos la siguiente hoja de estilo:

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 rasgado y los botones de desplazamiento pueden personalizarse aún más como sigue:

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);
}

Desde Qt 4.6 el botón cerrar puede personalizarse como sigue:

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

Personalizando QTableView

Supongamos que queremos que nuestro elemento seleccionado en QTableView tenga como fondo un fundido de color rosa chicle a blanco.

Vista de tabla con estilo personalizado

Esto es posible con la propiedad selection-background-color y la sintaxis requerida 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 puede personalizarse utilizando la siguiente hoja de estilo

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

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

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

Personalización de QToolBar

El fondo y el manejador de QToolBar se personaliza 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 QToolBox se personalizan utilizando 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;
}

Personalizando QToolButton

Hay tres tipos de QToolButtons.

El QToolButton no tiene menú. En este caso, el QToolButton tiene el mismo estilo que el QPushButton. Vea Personalizando QPushButton para un ejemplo.
El QToolButton tiene un menú y tiene el QToolButton::popupMode configurado como QToolButton::DelayedPopup o QToolButton::InstantPopup. En este caso, el QToolButton tiene el mismo estilo que un QPushButton con menú. Ver Personalización de QPushButton para un ejemplo del uso del pseudo estado menú-indicador.
El QToolButton tiene su QToolButton::popupMode ajustado a QToolButton::MenuButtonPopup. En este caso, le damos el siguiente estilo:

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 */
}

Personalizando QToolTip

QToolTip se personaliza exactamente como un QLabel. Además, para plataformas que lo soporten, la propiedad opacity puede ser establecida para ajustar la opacidad.

Por ejemplo,

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

Personalizando QTreeView

El color de fondo de las filas alternas puede personalizarse utilizando la siguiente hoja de estilo:

QTreeView {
    alternate-background-color: yellow;
}

Para proporcionar un fondo especial cuando se pasa el ratón 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 estilizan utilizando el subcontrol ::branch. La siguiente hoja de estilo codifica por colores 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 es colorida, se puede hacer un ejemplo más útil utilizando las siguientes imágenes:


vline.png	rama-más.png	rama-fin.png	rama-cerrada.png	rama-abierta.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 estilizadas

Errores comunes

Esta sección enumera algunos errores comunes al utilizar hojas de estilo.

QPushButton e imágenes

Al estilizar un QPushButton, a menudo es deseable usar una imagen como gráfico del botón. Es común probar la propiedad background-image, pero esto tiene una serie de inconvenientes: Por ejemplo, el fondo aparecerá a menudo oculto tras la decoración del botón, porque no se considera un fondo. Además, si se cambia el tamaño del botón, todo el fondo se estirará o se pondrá en mosaico, lo que no siempre queda bien.

Es mejor utilizar la propiedad border-image, ya que siempre mostrará la imagen, independientemente del fondo (puede combinarla con un fondo si tiene valores alfa en él), y tiene ajustes especiales para tratar con el redimensionamiento del botón.

Considere el siguiente fragmento:

        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 producirá un botón con este aspecto:

Botón con fondo

Los números después de la url dan el número de píxeles superior, derecho, inferior e izquierdo, respectivamente. Estos números corresponden al borde y no deben estirarse cuando cambia el tamaño. Cada vez que cambie 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 éste:

Botón con tamaños de borde especificados

Con bordes

Botón sin bordes especificados

Sin bordes

Véase también Subconjunto HTML soportado y QStyle.

Hojas de estilo de referencia Gestión del diseño

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

Ejemplos de Hojas de Estilo Qt

Uso de las Hojas de Estilo

Personalizando los Colores de Primer Plano y Fondo

Personalización mediante propiedades dinámicas

Personalizando un QPushButton Usando el Modelo de Caja

Personalizando el subcontrol del indicador de menú de QPushButton

Ejemplo de selector complejo

Personalización de widgets específicos

Personalizando QAbstractScrollArea

Personalizando QCheckBox

Personalización de QComboBox

Personalizando QDockWidget

Personalización de QFrame

Personalizando QGroupBox

Personalización de QHeaderView

Personalizar QLineEdit

Personalizando QListView

Personalizando QMainWindow

Personalizando QMenu

Personalización de QMenuBar

Personalización de QProgressBar

Personalizando QPushButton

Personalización de QRadioButton

Personalización de QScrollBar

La personalización de QSizeGrip

Personalizando QSlider

Personalización de QSpinBox

Personalización de QSplitter

Personalizar QStatusBar

Personalizando QTabWidget y QTabBar

Personalizando QTableView

Personalización de QToolBar

Personalización de QToolBox

Personalizando QToolButton

Personalizando QToolTip

Personalizando QTreeView

Errores comunes

QPushButton e imágenes