En esta página

QPalette Class

La clase QPalette contiene grupos de colores para cada estado de los widgets. Más información...

Encabezado: #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 de Qt contienen una paleta y la utilizan para dibujarse a sí mismos. Esto hace que la interfaz de usuario sea fácilmente configurable y más sencilla de mantener coherente.

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

Los grupos de colores:

  • El grupo «Activo» se utiliza para la ventana que tiene el foco del teclado.
  • El grupo «Inactivo» se utiliza para el resto de ventanas.
  • El grupo «Desactivado» se utiliza para los widgets (no para las ventanas) que están desactivados por algún motivo.

Tanto las ventanas activas como las inactivas pueden contener widgets desactivados. (Los widgets desactivados suelen denominarse «inaccesibles» o «atenuados»).

En la mayoría de los estilos, «Activo» e «Inactivo» tienen el mismo aspecto.

Se pueden establecer colores y pinceles para roles concretos en cualquiera de los grupos de color de una paleta mediante setColor() y setBrush(). Un grupo de color contiene un conjunto de colores que utilizan los widgets para dibujarse a sí mismos. Recomendamos que los widgets utilicen roles de grupo de color de la paleta, como «foreground» y «base», en lugar de colores literales como «red» o «turquoise». Los roles de color se enumeran y definen en la documentación de ColorRole.

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

Para modificar un grupo de colores, se deben llamar a las funciones setColor() y setBrush(), dependiendo de si se desea un color puro o un patrón de mapa de píxeles.

También existen los métodos de lectura correspondientes color() y brush(), así como una función de conveniencia de uso habitual para obtener la ColorRole del ColorGroup actual: window(), windowText(), base(), etc.

Se puede copiar una paleta utilizando el constructor de copia y comprobar si dos paletas son idénticas mediante ` isCopyOf()`.

QPalette está optimizada mediante el uso del uso compartido implícito, por lo que resulta muy eficiente pasar objetos QPalette como argumentos.

Advertencia: Algunos estilos no utilizan la paleta para todos los dibujos; por ejemplo, si hacen uso de motores de temas nativos. Este es el caso tanto de los estilos de Windows Vista como de los de macOS.

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

Documentación sobre tipos de miembros

enum QPalette::ColorGroup

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

enum QPalette::ColorRole

Papeles según el color

La enumeración ColorRole define los diferentes roles simbólicos de color que se utilizan en las interfaces gráficas de usuario actuales.

Los roles principales 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 introducción de texto, pero también puede emplearse para otros elementos gráficos, como el fondo de las listas desplegables de los cuadros combinados y los controladores 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 para QToolTip y QWhatsThis. Las descripciones emergentes utilizan el grupo de colores «Inactivo» de QPalette, ya que las descripciones emergentes no son ventanas activas.
QPalette::ToolTipText19Se utiliza como color de primer plano para QToolTip y QWhatsThis. Las descripciones emergentes utilizan el grupo de colores «Inactivo» de QPalette, ya que las descripciones emergentes no son ventanas activas.
QPalette::PlaceholderText20Se utiliza como color de marcador de posición para diversos widgets de entrada de texto. Este valor de enumeración se ha introducido en Qt 5.12
QPalette::Text6El color de primer plano utilizado con Base. Suele ser el mismo que el de WindowText; en ese caso, debe ofrecer un buen contraste con Window y Base.
QPalette::Button1El color de fondo general de los botones. Este fondo puede ser diferente de Window, ya que algunos estilos requieren un color de fondo distinto para los botones.
QPalette::ButtonText8Un color de primer plano que se utiliza junto con el color Button.
QPalette::BrightText7Un color de texto muy diferente al de WindowText, y que contrasta bien, por ejemplo, con Dark. Se suele utilizar para texto que debe mostrarse en lugares donde Text o WindowText ofrecerían un contraste insuficiente, como en los botones pulsados. Ten en cuenta que los colores de texto pueden utilizarse para otros elementos además de las palabras; aunque suelen emplearse para el texto, es bastante habitual utilizar los roles de color de texto para líneas, iconos, etc.

Existen algunas funciones de color que se utilizan principalmente para efectos de bisel y sombra en 3D. Todas ellas se derivan normalmente de Window y se utilizan de formas que dependen de esa relación. Por ejemplo, los botones dependen de ello para que los biseles tengan un aspecto atractivo, y las barras de desplazamiento de Motif dependen de que Mid sea ligeramente diferente de Window.

ConstanteValorDescripción
QPalette::Light2Color más claro que el de 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 suele contrastar o complementar los colores Base, Ventana y Botón. Normalmente representa la elección del usuario en cuanto a la personalización del escritorio. Un caso de uso típico es el diseño de componentes interactivos. A menos que se establezca explícitamente, el valor por defecto es Resaltado.
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::LinkVisited15Color de texto utilizado para los hipervínculos ya visitados. Por defecto, el color de los enlaces visitados es Qt::magenta.

Ten en cuenta que en Qt no utilizamos los roles « Link » y « LinkVisited » al representar texto enriquecido, y que recomendamos utilizar CSS y la función QTextDocument::setDefaultStyleSheet() para modificar el aspecto 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 ningún rol.

Documentación de funciones miembro

QPalette::QPalette()

Crea un objeto de paleta vacío sin ningún rol de color establecido.

Cuando se utiliza como paleta de un objeto ` QWidget `, los colores se resuelven tal y como se describe en ` QWidget::setPalette()`.

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

QPalette::QPalette(Qt::GlobalColor button)

Crea una paleta a partir del color button. Los demás colores se calculan automáticamente en función de este color. Window será también el color del botón.

QPalette::QPalette(const QColor &button)

Crea una paleta a partir del color button. Los demás colores se calculan automáticamente en función de este color. Window será también el color del botón.

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

Crea una paleta a partir de un color de tipo « button » y un « window ». Los demás colores se calculan automáticamente a partir de estos.

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)

Crea una paleta. Puedes pasar pinceles, mapas de píxeles o colores simples para las funciones « windowText », « button », « light », « dark », « mid », « text », « bright_text », « base » y « window ».

Véase también QBrush.

QPalette::QPalette(const QPalette &p)

Crea una copia de ` p`.

Este constructor es rápido gracias al uso compartido implícito.

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

Crea una instancia de QPalette mediante la construcción por movimiento, haciendo que apunte al mismo objeto al que apuntaba other.

Una vez que se ha realizado el movimiento, solo se puede asignar un valor a ` other` o destruirlo. Cualquier otra operación dará lugar a un comportamiento indefinido.

[noexcept] QPalette::~QPalette()

Elimina 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 texto brillante en primer plano 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 con 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 configurado para el color dado role en el ColorGroup actual.

Esta es una función sobrecargada.

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

const QBrush &QPalette::button() const

Devuelve el pincel de botón del grupo de colores 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 `. Diferentes objetos ` QPalette ` pueden tener la misma clave si hacen referencia al mismo contenido.

La clave cacheKey() cambiará cuando se modifique la paleta.

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

Devuelve el color de la entrada de color especificada group, utilizada 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 ColorGroup actual.

Esta es 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 resaltado 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 « ColorGroup » ( cg ) y « ColorRole » ( cr ) se han establecido previamente en esta paleta; en caso contrario, devuelve « false ».

El valor de « 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.

La función « 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 entre sí, es decir, si una de ellas se creó como copia de la otra y ninguna de las dos se ha modificado 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 de forma rápida) si el grupo de colores « cg1 » es igual a « cg2 »; en caso contrario, devuelve « false ».

const QBrush &QPalette::light() const

Devuelve el pincel claro del grupo de colores actual.

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

Devuelve el pincel de texto de los enlaces no visitados 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 de marcador de posición del grupo de colores actual.

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

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

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

Devuelve un nuevo objeto « 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 hayan establecido 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 indicado role en el valor 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, utilizado para el color dado role, en brush.

Esta es una función sobrecargada.

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

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

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

Véanse 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, en el color sólido especificado color.

Esta es una función sobrecargada.

Véanse 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 el grupo en cg. Puedes pasar pinceles, mapas de píxeles o colores simples 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)

Sustituye esta instancia de la paleta por other. Esta operación es muy rápida y nunca falla.

const QBrush &QPalette::text() const

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

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

const QBrush &QPalette::toolTipBase() const

Devuelve el pincel base de las descripciones emergentes del grupo de colores actual. Este pincel lo utilizan QToolTip y QWhatsThis.

Nota: Las descripcionesemergentes utilizan el grupo de colores «Inactivo» de QPalette, ya que las descripciones emergentes no son ventanas activas.

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

const QBrush &QPalette::toolTipText() const

Devuelve el pincel de texto de las descripciones emergentes del grupo de colores actual. Este pincel lo utilizan QToolTip y QWhatsThis.

Nota: Las descripcionesemergentes utilizan el grupo de colores «Inactivo» de QPalette, ya que las descripciones emergentes no son ventanas activas.

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

const QBrush &QPalette::window() const

Devuelve el pincel de 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éanse también « ColorRole » y « brush()».

QPalette::operator QVariant() const

Devuelve la paleta como un 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: El valor actual de ` ColorGroup ` no se tiene en cuenta al comparar paletas

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

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

Asigna « other » a esta instancia de « QPalette ». .

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

Asigna « p » a esta paleta y devuelve una referencia a dicha paleta.

Esta operación es rápida gracias al uso compartido implícito.

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

Devuelve « true » (normalmente de forma rápida) si esta paleta es igual a « p »; en caso contrario, devuelve « false » (de forma lenta).

Nota: A la hora de comparar paletas, no se tiene en cuentalo siguiente:

Esta función se introdujo en Qt 6.6.

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

Elementos no miembros relacionados

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

Escribe la paleta « p » en el flujo « s » y devuelve una referencia al flujo.

Véase también el formato de los operadores de 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 el formato de los operadores de 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.