En esta página

QPalette Class

La clase QPalette contiene grupos de colores para cada estado del widget. Más...

Cabecera: #include <QPalette>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Tipos Públicos

enum ColorGroup { Disabled, Active, Inactive, Normal }
enum ColorRole { Window, WindowText, Base, AlternateBase, ToolTipBase, …, NoRole }

Funciones Públicas

QPalette()
QPalette(Qt::GlobalColor button)
QPalette(const QColor &button)
QPalette(const QColor &button, const QColor &window)
QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
QPalette(const QPalette &p)
QPalette(QPalette &&other)
~QPalette()
(since 6.6) const QBrush &accent() const
const QBrush &alternateBase() const
const QBrush &base() const
const QBrush &brightText() const
const QBrush &brush(QPalette::ColorGroup group, QPalette::ColorRole role) const
const QBrush &brush(QPalette::ColorRole role) const
const QBrush &button() const
const QBrush &buttonText() const
qint64 cacheKey() const
const QColor &color(QPalette::ColorGroup group, QPalette::ColorRole role) const
const QColor &color(QPalette::ColorRole role) const
QPalette::ColorGroup currentColorGroup() const
const QBrush &dark() const
const QBrush &highlight() const
const QBrush &highlightedText() const
bool isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const
bool isCopyOf(const QPalette &p) const
bool isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const
const QBrush &light() const
const QBrush &link() const
const QBrush &linkVisited() const
const QBrush &mid() const
const QBrush &midlight() const
const QBrush &placeholderText() const
QPalette resolve(const QPalette &other) const
void setBrush(QPalette::ColorRole role, const QBrush &brush)
void setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)
void setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)
void setColor(QPalette::ColorRole role, const QColor &color)
void setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
void setCurrentColorGroup(QPalette::ColorGroup cg)
const QBrush &shadow() const
void swap(QPalette &other)
const QBrush &text() const
const QBrush &toolTipBase() const
const QBrush &toolTipText() const
const QBrush &window() const
const QBrush &windowText() const
operator QVariant() const
bool operator!=(const QPalette &p) const
QPalette &operator=(QPalette &&other)
QPalette &operator=(const QPalette &p)
(since 6.6) bool operator==(const QPalette &p) const
QDataStream &operator<<(QDataStream &s, const QPalette &p)
QDataStream &operator>>(QDataStream &s, QPalette &p)

Descripción Detallada

Una paleta consta de tres grupos de colores: Activo, Desactivado e Inactivo. Todos los widgets en Qt contienen una paleta y usan su paleta para dibujarse a sí mismos. Esto hace que la interfaz de usuario sea fácilmente configurable y más fácil de mantener consistente.

Si creas un nuevo widget, te recomendamos encarecidamente que utilices los colores de la paleta en lugar de codificar colores específicos.

Los grupos de colores:

  • El grupo Activo se utiliza para la ventana que tiene el foco del teclado.
  • El grupo Inactivo se utiliza para otras ventanas.
  • El grupo Desactivado se utiliza para los widgets (no ventanas) que están desactivados por alguna razón.

Tanto las ventanas activas como las inactivas pueden contener widgets desactivados. (Los widgets desactivados suelen denominarse inaccesibles o en gris).

En la mayoría de los estilos, Activa e Inactiva tienen el mismo aspecto.

Los colores y pinceles pueden establecerse para funciones concretas en cualquiera de los grupos de colores de una paleta con setColor() y setBrush(). Un grupo de colores contiene un grupo de colores utilizados por los widgets para dibujarse a sí mismos. Recomendamos que los widgets utilicen roles de grupos de colores de la paleta como "primer plano" y "base" en lugar de colores literales como "rojo" o "turquesa". Los roles de color se enumeran y definen en la documentación de ColorRole.

Recomendamos encarecidamente utilizar la paleta por defecto del estilo actual (devuelta por QGuiApplication::palette()) y modificarla según sea necesario. Esto lo hacen los widgets de Qt cuando se dibujan.

Para modificar un grupo de colores se llama a las funciones setColor() y setBrush(), dependiendo de si se desea un color puro o un patrón pixmap.

También existen los correspondientes getters color() y brush(), y una función de uso común para obtener el ColorRole para el ColorGroup actual: window(), windowText(), base(), etc.

Puede copiar una paleta con el constructor copy y comprobar si dos paletas son idénticas con isCopyOf().

QPalette está optimizado mediante el uso de compartición implícita, por lo que es muy eficiente pasar objetos QPalette como argumentos.

Advertencia: Algunos estilos no utilizan la paleta para todo el dibujo, por ejemplo, si hacen uso de motores de temas nativos. Este es el caso de los estilos Windows Vista y macOS.

Véase también QApplication::setPalette(), QWidget::setPalette(), y QColor.

Documentación de tipos de miembros

enum QPalette::ColorGroup

ConstanteValorDescripción
QPalette::Disabled1
QPalette::Active0
QPalette::Inactive2
QPalette::NormalActivesinónimo de Activo

enum QPalette::ColorRole

Roles de color

El enum ColorRole define los diferentes roles simbólicos de color utilizados en las interfaces gráficas de usuario actuales.

Los roles centrales son

ConstanteValorDescripción
QPalette::Window10Un color de fondo general.
QPalette::WindowText0Un color de primer plano general.
QPalette::Base9Se utiliza principalmente como color de fondo para los widgets de entrada de texto, pero también se puede utilizar para otras pinturas, como el fondo de las listas desplegables de los combobox y los tiradores de la barra de herramientas. Suele ser blanco u otro color claro.
QPalette::AlternateBase16Se utiliza como color de fondo alternativo en vistas con colores de fila alternos (véase QAbstractItemView::setAlternatingRowColors()).
QPalette::ToolTipBase18Se utiliza como color de fondo en QToolTip y QWhatsThis. Los consejos de herramientas utilizan el grupo de colores Inactivo de QPalette, porque los consejos de herramientas no son ventanas activas.
QPalette::ToolTipText19Se utiliza como color de primer plano para QToolTip y QWhatsThis. Los tool tips utilizan el grupo de colores Inactive de QPalette, porque los tool tips no son ventanas activas.
QPalette::PlaceholderText20Se utiliza como color de marcador de posición para varios widgets de entrada de texto. Este valor enum ha sido introducido en Qt 5.12
QPalette::Text6El color de primer plano utilizado con Base. Suele ser el mismo que el de WindowText, en cuyo caso debe proporcionar un buen contraste con Window y Base.
QPalette::Button1El color de fondo general del botón. Este fondo puede ser diferente de Window ya que algunos estilos requieren un color de fondo diferente para los botones.
QPalette::ButtonText8Un color de primer plano utilizado con el color Button.
QPalette::BrightText7Un color de texto que es muy diferente de WindowText, y contrasta bien con, por ejemplo, Dark. Suele utilizarse para texto que debe dibujarse en lugares en los que Text o WindowText darían poco contraste, como en los botones pulsadores pulsados. Tenga en cuenta que los colores de texto pueden usarse para otras cosas además de palabras; los colores de texto se usan normalmente para texto, pero es bastante común usar los roles de color de texto para líneas, iconos, etc.

Hay algunos roles de color que se utilizan sobre todo para efectos de bisel y sombra en 3D. Todos ellos se derivan normalmente de Window, y se utilizan de formas que dependen de esa relación. Por ejemplo, los botones dependen de ella para que los biseles tengan un aspecto atractivo, y las barras de desplazamiento de Motif dependen de Mid para ser ligeramente diferentes de Window.

ConstanteValorDescripción
QPalette::Light2Color más claro que Button.
QPalette::Midlight3Entre Button y Light.
QPalette::Dark4Más oscuro que Button.
QPalette::Mid5Entre Button y Dark.
QPalette::Shadow11Un color muy oscuro. Por defecto, el color de la sombra es Qt::black.

Los elementos seleccionados (marcados) tienen dos funciones:

ConstanteValorDescripción
QPalette::Highlight12Un color para indicar un elemento seleccionado o el elemento actual. Por defecto, el color de resaltado es Qt::darkBlue.
QPalette::Accent (since Qt 6.6)21Un color que normalmente contrasta o complementa los colores Base, Ventana y Botón. Suele representar la opción de personalización del escritorio elegida por los usuarios. El estilo de los componentes interactivos es un caso de uso típico. A menos que se defina explícitamente, por defecto es Resaltar.
QPalette::HighlightedText13Un color de texto que contrasta con Highlight. Por defecto, el color del texto resaltado es Qt::white.

Hay dos funciones de color relacionadas con los hipervínculos:

ConstanteValorDescripción
QPalette::Link14Color de texto utilizado para los hipervínculos no visitados. Por defecto, el color del enlace es Qt::blue.
QPalette::LinkVisited15Un color de texto utilizado para los hipervínculos ya visitados. Por defecto, el color del enlace visitado es Qt::magenta.

Tenga en cuenta que no utilizamos las funciones Link y LinkVisited al renderizar texto enriquecido en Qt, y que le recomendamos que utilice CSS y la función QTextDocument::setDefaultStyleSheet() para alterar la apariencia de los enlaces. Por ejemplo

    QTextBrowser browser;
    QColor linkColor(Qt::red);
    QString sheet = QString::fromLatin1("a { text-decoration: underline; color: %1 }").arg(linkColor.name());
    browser.document()->setDefaultStyleSheet(sheet);
ConstanteValorDescripción
QPalette::NoRole17Sin rol; este rol especial se utiliza a menudo para indicar que no se ha asignado un rol.

Documentación de la función de miembro

QPalette::QPalette()

Construye un objeto paleta vacío sin roles de color establecidos.

Cuando se utiliza como paleta de un QWidget los colores se resuelven como se describe en QWidget::setPalette().

Véase también QApplication::setPalette() y QApplication::palette().

QPalette::QPalette(Qt::GlobalColor button)

Construye una paleta a partir del color button. Los otros colores se calculan automáticamente, basándose en este color. Window será también el color del botón.

QPalette::QPalette(const QColor &button)

Construye una paleta a partir del color button. Los otros colores se calculan automáticamente, basándose en este color. Window será también el color del botón.

QPalette::QPalette(const QColor &button, const QColor &window)

Construye una paleta a partir de un color button y un window. Los otros colores se calculan automáticamente, basándose en estos colores.

QPalette::QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)

Construye una paleta. Puede pasar pinceles, mapas de píxeles o colores planos para windowText, button, light, dark, mid, text, bright_text, base y window.

Véase también QBrush.

QPalette::QPalette(const QPalette &p)

Construye una copia de p.

Este constructor es rápido gracias a la compartición implícita.

[noexcept] QPalette::QPalette(QPalette &&other)

Mover-construye una instancia de QPalette, haciendo que apunte al mismo objeto al que apuntaba other.

Después de ser movida, sólo se puede asignar o destruir other. Cualquier otra operación provocará un comportamiento indefinido.

[noexcept] QPalette::~QPalette()

Destruye la paleta.

[since 6.6] const QBrush &QPalette::accent() const

Devuelve el pincel de acento del grupo de colores actual.

Esta función se introdujo en Qt 6.6.

Véase también ColorRole y brush().

const QBrush &QPalette::alternateBase() const

Devuelve el pincel base alternativo del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::base() const

Devuelve el pincel base del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::brightText() const

Devuelve el pincel de primer plano de texto brillante del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::brush(QPalette::ColorGroup group, QPalette::ColorRole role) const

Devuelve el pincel en el color especificado group, utilizado para el color dado role.

Véase también color(), setBrush() y ColorRole.

const QBrush &QPalette::brush(QPalette::ColorRole role) const

Devuelve el pincel que se ha establecido para el color dado role en el actual ColorGroup.

Esta es una función sobrecargada.

Véase también color(), setBrush() y ColorRole.

const QBrush &QPalette::button() const

Devuelve el pincel del botón del grupo de color actual.

Véase también ColorRole y brush().

const QBrush &QPalette::buttonText() const

Devuelve el pincel de primer plano del texto del botón del grupo de colores actual.

Véase también ColorRole y brush().

qint64 QPalette::cacheKey() const

Devuelve un número que identifica el contenido de este objeto QPalette. Distintos objetos QPalette pueden tener la misma clave si se refieren a los mismos contenidos.

El valor de cacheKey() cambiará cuando se modifique la paleta.

const QColor &QPalette::color(QPalette::ColorGroup group, QPalette::ColorRole role) const

Devuelve el color en el color especificado group, utilizado para el color dado role.

Véase también brush(), setColor() y ColorRole.

const QColor &QPalette::color(QPalette::ColorRole role) const

Devuelve el color que se ha establecido para el color dado role en el actual ColorGroup.

Se trata de una función sobrecargada.

Véase también brush() y ColorRole.

QPalette::ColorGroup QPalette::currentColorGroup() const

Devuelve el grupo de colores actual de la paleta.

Véase también setCurrentColorGroup().

const QBrush &QPalette::dark() const

Devuelve el pincel oscuro del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::highlight() const

Devuelve el pincel de realce del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::highlightedText() const

Devuelve el pincel de texto resaltado del grupo de colores actual.

Véase también ColorRole y brush().

bool QPalette::isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const

Devuelve true si los valores ColorGroup cg y ColorRole cr han sido establecidos previamente en esta paleta; en caso contrario devuelve false.

El ColorGroup cg debe ser menor que QPalette::NColorGroups, pero se puede utilizar QPalette::Current. En este caso, se utilizará el grupo de colores actual establecido previamente.

El ColorRole cr debe ser menor que QPalette::NColorRoles.

Véase también setBrush() y currentColorGroup().

bool QPalette::isCopyOf(const QPalette &p) const

Devuelve true si esta paleta y p son copias la una de la otra, es decir, una de ellas fue creada como copia de la otra y ninguna fue modificada posteriormente; en caso contrario devuelve false. Esto es mucho más estricto que la igualdad.

Véase también operator=() y operator==().

bool QPalette::isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const

Devuelve true (normalmente rápido) si el grupo de color cg1 es igual a cg2; en caso contrario devuelve false.

const QBrush &QPalette::light() const

Devuelve el pincel de luz del grupo de colores actual.

Véase también ColorRole y brush().

Devuelve el pincel de texto de enlace no visitado del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::linkVisited() const

Devuelve el pincel de texto del enlace visitado del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::mid() const

Devuelve el pincel medio del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::midlight() const

Devuelve el pincel de luz media del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::placeholderText() const

Devuelve el pincel de texto del marcador de posición del grupo de color actual.

Nota: Antes de Qt 5.12, el color del texto del marcador de posición se codificaba como QPalette::text().color() con un alfa de 128 aplicado. En Qt 6, es un color independiente.

Ver también ColorRole y brush().

QPalette QPalette::resolve(const QPalette &other) const

Devuelve un nuevo QPalette que es la unión de esta instancia y other. Los roles de color establecidos en esta instancia tienen prioridad. Los roles que no se establezcan en esta instancia se tomarán de other.

Véase también isBrushSet.

void QPalette::setBrush(QPalette::ColorRole role, const QBrush &brush)

Establece el pincel para el color dado role al especificado brush para todos los grupos de la paleta.

Véase también brush(), setColor(), y ColorRole.

void QPalette::setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)

Establece el pincel en el color especificado group, usado para el color dado role, a brush.

Esta es una función sobrecargada.

Ver también brush(), setColor(), y ColorRole.

void QPalette::setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)

Establece el color en el color especificado group, utilizado para el color dado role, al sólido especificado color.

Véase también setBrush(), color(), y ColorRole.

void QPalette::setColor(QPalette::ColorRole role, const QColor &color)

Establece el color utilizado para el color dado role, en todos los grupos de colores, al sólido especificado color.

Se trata de una función sobrecargada.

Véase también brush(), setColor(), y ColorRole.

void QPalette::setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)

Establece un grupo en cg. Puede pasar pinceles, mapas de píxeles o colores planos para windowText, button, light, dark, mid, text, bright_text, base y window.

Véase también QBrush.

void QPalette::setCurrentColorGroup(QPalette::ColorGroup cg)

Establece el grupo de colores actual de la paleta en cg.

Véase también currentColorGroup().

const QBrush &QPalette::shadow() const

Devuelve el pincel de sombra del grupo de colores actual.

Véase también ColorRole y brush().

[noexcept] void QPalette::swap(QPalette &other)

Intercambia esta instancia de paleta con other. Esta operación es muy rápida y nunca falla.

const QBrush &QPalette::text() const

Devuelve el pincel de primer plano de texto del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::toolTipBase() const

Devuelve el pincel base de la punta de la herramienta del grupo de color actual. Este pincel es utilizado por QToolTip y QWhatsThis.

Nota: Las puntas de herramienta utilizan el grupo de color Inactivo de QPalette, porque las puntas de herramienta no son ventanas activas.

Véase también ColorRole y brush().

const QBrush &QPalette::toolTipText() const

Devuelve el pincel de texto de la punta de la herramienta del grupo de color actual. Este pincel es utilizado por QToolTip y QWhatsThis.

Nota: Los tool tips usan el grupo de color Inactive de QPalette, porque los tool tips no son ventanas activas.

Véase también ColorRole y brush().

const QBrush &QPalette::window() const

Devuelve el pincel de la ventana (fondo general) del grupo de colores actual.

Véase también ColorRole y brush().

const QBrush &QPalette::windowText() const

Devuelve el pincel de texto de ventana (primer plano general) del grupo de colores actual.

Véase también ColorRole y brush().

QPalette::operator QVariant() const

Devuelve la paleta como QVariant

bool QPalette::operator!=(const QPalette &p) const

Devuelve true (lentamente) si esta paleta es diferente de p; en caso contrario devuelve false (normalmente rápidamente).

Nota: La ColorGroup actual no se tiene en cuenta al comparar paletas.

Véase también operator==().

[noexcept] QPalette &QPalette::operator=(QPalette &&other)

Mover-asigna other a esta instancia QPalette.

QPalette &QPalette::operator=(const QPalette &p)

Asigna p a esta paleta y devuelve una referencia a la misma.

Esta operación es rápida gracias a la compartición implícita.

[since 6.6] bool QPalette::operator==(const QPalette &p) const

Devuelve true (normalmente rápido) si esta paleta es igual a p; en caso contrario devuelve false (lentamente).

Nota: Al comparar paletas no se tiene en cuenta

Esta función se introdujo en Qt 6.6.

Véase también operator!=().

No miembros relacionados

QDataStream &operator<<(QDataStream &s, const QPalette &p)

Escribe la paleta, p al stream s y devuelve una referencia al stream.

Véase también Formato de los operadores QDataStream.

QDataStream &operator>>(QDataStream &s, QPalette &p)

Lee una paleta del flujo, s en la paleta p, y devuelve una referencia al flujo.

Véase también Formato de los operadores QDataStream.

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