En esta página

Personalización de « Qt Widgets » mediante hojas de estilo

Al utilizar hojas de estilo, cada widget se trata como un cuadro con cuatro rectángulos concéntricos: el rectángulo de margen, el rectángulo de borde, el rectángulo de relleno y el rectángulo de contenido. El modelo de cuadro describe esto con más detalle.

El modelo de cuadro

Los cuatro rectángulos concéntricos se representan conceptualmente de la siguiente manera:

Diagrama del modelo de caja CSS para el diseño de maquetación

  • El margen queda fuera del borde.
  • El borde se dibuja entre el margen y el relleno.
  • El relleno se encuentra dentro del borde, entre este y el contenido real.
  • El contenido es lo que queda del widget o subcontrol original una vez que hemos eliminado el margen, el borde y el relleno.

Las propiedades «margin», «border-width» y «padding» tienen por defecto el valor cero. En ese caso, los cuatro rectángulos (margin, border, padding y content) coinciden exactamente.

Puedes especificar un fondo para el widget mediante la propiedad «background-image ». De forma predeterminada, la imagen de fondo solo se dibuja en el área situada dentro del borde. Esto se puede modificar mediante la propiedad «background-clip ». Puedes utilizar «background-repeat» y «background-origin» para controlar la repetición y el origen de la imagen de fondo.

Una imagen de fondo no se adapta al tamaño del widget. Para proporcionar una «piel» o fondo que se adapte al tamaño del widget, hay que utilizar border-image. Dado que la propiedad border-image proporciona un fondo alternativo, no es necesario especificar una imagen de fondo cuando se especifica border-image. En caso de que se especifiquen ambas, la imagen de borde se superpone a la imagen de fondo.

Además, la propiedad `image` puede utilizarse para dibujar una imagen sobre la `border-image`. La imagen especificada no se repite ni se estira y, cuando su tamaño no coincide con el del widget, su alineación se especifica mediante la propiedad `image-position`. A diferencia de `background-image` y `border-image`, se puede especificar un SVG en la propiedad `image`; en ese caso, la imagen se escala automáticamente según el tamaño del widget.

Los pasos para representar una regla son los siguientes:

  • Establecer el recorte para toda la operación de representación (border-radius)
  • Dibujar el fondo (background-image)
  • Dibujar el borde (border-image, border)
  • Dibujar la imagen superpuesta (image)

Subcontroles

Un widget se considera una jerarquía (árbol) de subcontroles dibujados unos encima de otros. Por ejemplo, el QComboBox dibuja el subcontrol desplegable seguido del subcontrol de flecha hacia abajo. Así pues, un QComboBox se representa de la siguiente manera:

  • Representar la regla QComboBox { }
  • Representar la regla QComboBox::drop-down { }
  • Representar la regla QComboBox::down-arrow { }

Los subcontroles comparten una relación padre-hijo. En el caso de QComboBox, el padre de down-arrow es el drop-down y el padre de drop-down es el propio widget. Los subcontroles se sitúan dentro de su padre mediante las propiedades subcontrol-position y subcontrol-origin.

Una vez posicionados, se puede aplicar estilo a los subcontroles utilizando el modelo de caja.

Nota: En el caso de widgets complejos como QComboBox y QScrollBar, si se personaliza una propiedad o un subcontrol, también deben personalizarse todas las demás propiedades o subcontroles.

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