Cómo aplicar estilos a una casilla de selección: guía paso a paso
Esta página sigue el proceso de una casilla de selección desde el momento en que recibe un evento de dibujo hasta que el estilo termina de dibujarse. Muestra cómo el widget construye su opción de estilo, cómo un « QCommonStyle » divide el elemento en partes y cómo un « QProxyStyle » sustituye una de esas partes. La mayoría de los widgets siguen la misma estructura, por lo que la misma estrategia de lectura funciona para todos ellos: busca la opción de estilo que crea el widget, busca los elementos que dibuja y lee la implementación de QCommonStyle de dichos elementos.
El widget crea una opción de estilo
QCheckBox utiliza QStyleOptionButton. Su función « initStyleOption() » completa la opción de la siguiente manera, ligeramente simplificada:
opt.initFrom(q);
if (down)
opt.state |= QStyle::State_Sunken;
if (tristate && noChange)
opt.state |= QStyle::State_NoChange;
else
opt.state |= checked ? QStyle::State_On : QStyle::State_Off;
if (q->testAttribute(Qt::WA_Hover) && q->underMouse()) {
if (hovering)
opt.state |= QStyle::State_MouseOver;
else
opt.state &= ~QStyle::State_MouseOver;
}
opt.text = text;
opt.icon = icon;
opt.iconSize = q->iconSize();QStyleOption::initFrom() establece la información que comparten todos los widgets. Su implementación se resume en lo siguiente:
state = QStyle::State_None;
if (widget->isEnabled())
state |= QStyle::State_Enabled;
if (widget->hasFocus())
state |= QStyle::State_HasFocus;
if (widget->window()->testAttribute(Qt::WA_KeyboardFocusChange))
state |= QStyle::State_KeyboardFocusChange;
if (widget->underMouse())
state |= QStyle::State_MouseOver;
if (widget->window()->isActiveWindow())
state |= QStyle::State_Active;
direction = widget->layoutDirection();
rect = widget->rect();
palette = widget->palette();
fontMetrics = widget->fontMetrics();State_Enabled se establece cuando el widget está habilitado, ` State_HasFocus ` cuando tiene el foco, ` State_KeyboardFocusChange ` cuando el usuario cambió el foco por última vez con el teclado y ` State_Active ` cuando la ventana del widget es la ventana activa. ` State_MouseOver ` se establece mientras el cursor del ratón se encuentra sobre el widget. Además del estado, ` initFrom() ` almacena en la opción la dirección de diseño, el rectángulo del widget, su paleta y sus métricas de fuente.
QCheckBox A continuación, añade su propio estado. Se establece « State_Sunken » mientras el usuario pulsa sobre la casilla, independientemente de si está marcada o no. Se establece « State_NoChange » para una casilla de tres estados parcialmente marcada; en caso contrario, « State_On » o « State_Off » reflejan el estado de la casilla. La opción también contiene el texto, el icono y el tamaño del icono. « QCheckBox » mantiene « State_MouseOver » solo mientras el widget tenga el atributo « WA_Hover », que normalmente establece un estilo en « polish()».
Supongamos que el usuario pulsa con el ratón la casilla de selección marcada de la siguiente captura de pantalla mientras tiene el foco. La captura de pantalla también muestra un botón de opción, que utiliza la misma estructura con PE_IndicatorRadioButton y CE_RadioButtonLabel:

En ese momento, su opción presenta los siguientes indicadores de estado:
| Indicador de estado | Establecida |
|---|---|
State_Sunken | Sí |
State_NoChange | No |
State_On | Sí |
State_Off | No |
State_MouseOver | Sí |
State_Enabled | Sí |
State_HasFocus | Sí |
State_KeyboardFocusChange | No |
State_Active | Sí |
El widget solicita al estilo que dibuje
QCheckBox se dibuja a sí mismo en ` paintEvent()` con un ` QStylePainter`, que envuelve las funciones de dibujo de ` QStyle`:
QStylePainter p;
QStyleOptionButton opt;
initStyleOption(&opt);
p.drawControl(QStyle::CE_CheckBox, opt);Eso es todo lo que hace el widget. Todo lo demás ocurre en el estilo.
QCommonStyle divide el elemento en partes
QCommonStyle gestiona ` CE_CheckBox ` solicitando los rectángulos de sus dos subelementos, ` SE_CheckBoxIndicator ` y ` SE_CheckBoxContents`, y dibujando un elemento en cada uno de ellos. Si la casilla de selección tiene el foco, también dibuja el marco de foco:
QStyleOptionButton subopt = *btn;
subopt.rect = subElementRect(QStyle::SE_CheckBoxIndicator, btn, widget);
proxy()->drawPrimitive(QStyle::PE_IndicatorCheckBox, &subopt, p, widget);
subopt.rect = subElementRect(QStyle::SE_CheckBoxContents, btn, widget);
proxy()->drawControl(QStyle::CE_CheckBoxLabel, &subopt, p, widget);
if (btn->state & State_HasFocus) {
QStyleOptionFocusRect fropt;
fropt.QStyleOption::operator=(*btn);
fropt.rect = subElementRect(QStyle::SE_CheckBoxFocusRect, btn, widget);
proxy()->drawPrimitive(QStyle::PE_FrameFocusRect, &fropt, p, widget);
}Fíjate en las llamadas a ` proxy() `. Un estilo siempre dibuja sus elementos hijos mediante ` proxy()` para que un ` QProxyStyle ` que lo envuelva tenga la oportunidad de sobrescribirlos.
CE_CheckBoxLabel También se implementa en QCommonStyle:
const QStyleOptionButton *btn = qstyleoption_cast<const QStyleOptionButton *>(opt);
uint alignment = visualAlignment(btn->direction, Qt::AlignLeft | Qt::AlignVCenter);
if (!proxy()->styleHint(SH_UnderlineShortcut, btn, widget))
alignment |= Qt::TextHideMnemonic;
QPixmap pix;
QRect textRect = btn->rect;
if (!btn->icon.isNull()) {
const auto dpr = p->device()->devicePixelRatio();
pix = btn->icon.pixmap(btn->iconSize, dpr,
btn->state & State_Enabled ? QIcon::Normal : QIcon::Disabled);
proxy()->drawItemPixmap(p, btn->rect, alignment, pix);
if (btn->direction == Qt::RightToLeft)
textRect.setRight(textRect.right() - btn->iconSize.width() - 4);
else
textRect.setLeft(textRect.left() + btn->iconSize.width() + 4);
}
if (!btn->text.isEmpty()){
proxy()->drawItemText(p, textRect, alignment | Qt::TextShowMnemonic,
btn->palette, btn->state & State_Enabled, btn->text, QPalette::WindowText);
}visualAlignment() ajusta la alineación según la dirección de maquetación. El estilo dibuja el icono, si lo hay, y reduce el rectángulo de texto restante en consecuencia. drawItemText() dibuja el texto teniendo en cuenta la alineación, la dirección de maquetación y el mnemónico, y utiliza la paleta para seleccionar el color del texto. Dibujar una etiqueta implica muchos detalles, y la clase base los gestiona bien, por lo que un estilo personalizado rara vez necesita reimplementarlo.
Un estilo proxy sustituye el indicador
El indicador, PE_IndicatorCheckBox, es donde difieren los estilos, por lo que es la parte que hay que sustituir. La siguiente subclase de QProxyStyle dibuja un indicador redondeado a partir de los colores de la paleta de la opción y reenvía todos los demás elementos al estilo base:
class CheckBoxStyle : public QProxyStyle
{
public:
using QProxyStyle::QProxyStyle;
void drawPrimitive(PrimitiveElement element, const QStyleOption *option,
QPainter *painter, const QWidget *widget) const override;
};
void CheckBoxStyle::drawPrimitive(PrimitiveElement element, const QStyleOption *option,
QPainter *painter, const QWidget *widget) const
{
if (element != PE_IndicatorCheckBox) {
QProxyStyle::drawPrimitive(element, option, painter, widget);
return;
}
const bool enabled = option->state & State_Enabled;
const QPalette::ColorGroup group = !enabled ? QPalette::Disabled
: option->state & State_Active ? QPalette::Active
: QPalette::Inactive;
const QPalette &palette = option->palette;
const QRect rect = option->rect.adjusted(1, 1, -1, -1);
painter->save();
painter->setRenderHint(QPainter::Antialiasing);
// Frame and background: highlight the frame while the mouse hovers over
// the indicator, and darken the background while it's pressed.
QColor frameColor = palette.color(group, QPalette::Mid);
if (enabled && (option->state & State_MouseOver))
frameColor = palette.color(group, QPalette::Highlight);
const QPalette::ColorRole fillRole =
option->state & State_Sunken ? QPalette::Mid : QPalette::Base;
painter->setPen(frameColor);
painter->setBrush(palette.brush(group, fillRole));
painter->drawRoundedRect(rect, 2, 2);
// Check mark for State_On, a filled square for the partially checked
// State_NoChange, nothing for State_Off.
const QRect inner = rect.adjusted(3, 3, -3, -3);
if (option->state & State_On) {
painter->setPen(QPen(palette.color(group, QPalette::Text), 2));
painter->drawLine(inner.left(), inner.center().y(),
inner.center().x(), inner.bottom());
painter->drawLine(inner.center().x(), inner.bottom(),
inner.right(), inner.top());
} else if (option->state & State_NoChange) {
painter->fillRect(inner, palette.brush(group, QPalette::Text));
}
painter->restore();
}La implementación lee toda su información de la opción. Selecciona el grupo de colores de State_Enabled y State_Active, resalta el marco mientras State_MouseOver está activado, oscurece el fondo mientras State_Sunken está activado y dibuja una marca de verificación para State_On o un cuadrado relleno para State_NoChange. Dado que todos los colores proceden de la paleta, el indicador sigue la paleta de la aplicación y funciona tanto en esquemas de color claro como oscuro. Además, guarda y restaura el «painter», de modo que la clase base encuentra el «painter» en el estado que espera.
El mismo indicador aparece siempre que el estilo dibuja PE_IndicatorCheckBox: en casillas de selección, en cuadros de grupo marcables y en vistas de elementos que lo utilizan para las marcas de verificación. Esa reutilización es la razón por la que existen los elementos primitivos.
Para utilizar el estilo, instálalo antes de que la aplicación cree sus widgets:
int main(int argc, char *argv[])
{
QApplication::setStyle(new CheckBoxStyle);
QApplication app(argc, argv);
QCheckBox box("Send me updates");
box.show();
return app.exec();
}Aplica el mismo razonamiento a otros widgets
Para saber cómo se dibuja un widget, no es necesario leer todo el código. Normalmente basta con saber qué elementos de estilo dibuja el widget, qué estados establece y qué contiene su opción de estilo. El widget crea una opción y llama al estilo una o más veces; el estilo dibuja los elementos que el widget solicita. La Referencia de estilos de widgets enumera exactamente eso para cada widget.
Véase también «Cómo dibuja un estilo un widget», «Referencia de estilos de widgets», QProxyStyle y QStyleOptionButton.
© 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.