QgsColorWidget class

A base class for interactive color widgets.

Reference

Widgets can either allow setting a single component of a color (e.g., the red or green components), or an entire color. The QgsColorWidget also keeps track of any explicitly set hue for the color, so that this information is not lost when the widget is set to a color with an ambiguous hue (e.g., black or white shades).

Derived classes

class QgsColorBox: A color box widget.
class QgsColorPreviewWidget: A preview box which displays one or two colors as swatches.
class QgsColorRampWidget: A color ramp widget.
class QgsColorSliderWidget: A composite horizontal color ramp widget and associated spinbox for manual value entry.
class QgsColorTextWidget: A line edit widget which displays colors as text and accepts string representations of colors.
class QgsColorWheel: A color wheel widget.

Public types

enum ColorComponent { Multiple = 0, Red, Green, Blue, Hue, Saturation, Value, Alpha }: Specifies the color component which the widget alters.

Public static functions

static auto createDragIcon(const QColor& color) -> QPixmap: Create an icon for dragging colors.

Constructors, destructors, conversion operators

QgsColorWidget(QWidget* parent = nullptr, ColorComponent component = Multiple): Construct a new color widget.

Public functions

auto color() const -> QColor: Returns the current color for the widget.
auto component() const -> ColorComponent: Returns the color component which the widget controls.
auto componentValue() const -> int: Returns the current value of the widget's color component.

Signals

void colorChanged(const QColor& color): Emitted when the widget's color changes.
void hovered(): Emitted when mouse hovers over widget.

Public slots

void setColor(const QColor& color, bool emitSignals = false) virtual: Sets the color for the widget.
void setComponent(QgsColorWidget::ColorComponent component) virtual: Sets the color component which the widget controls.
void setComponentValue(int value) virtual: Alters the widget's color by setting the value for the widget's color component.

Protected static functions

static auto transparentBackground() -> const QPixmap&: Generates a checkboard pattern pixmap for use as a background to transparent colors.

Protected functions

void alterColor(QColor& color, QgsColorWidget::ColorComponent component, int newValue) const: Alters a color by modifiying the value of a specific color component.
auto componentRange() const -> int: Returns the range of valid values for the color widget's component.
auto componentRange(ColorComponent component) const -> int: Returns the range of valid values a color component.
auto componentValue(ColorComponent component) const -> int: Returns the value of a component of the widget's current color.
auto hue() const -> int: Returns the hue for the widget.

Protected variables

int mExplicitHue: QColor wipes the hue information when it is ambiguous (e.g., for saturation = 0).

Enum documentation

enum QgsColorWidget::ColorComponent

Specifies the color component which the widget alters.

Enumerators
Multiple	Widget alters multiple color components.
Red	Red component of color.
Green	Green component of color.
Blue	Blue component of color.
Hue	Hue component of color (based on HSV model)
Saturation	Saturation component of color (based on HSV model)
Value	Value component of color (based on HSV model)
Alpha	Alpha component (opacity) of color.

Function documentation

static QPixmap QgsColorWidget::createDragIcon(const QColor& color)

Create an icon for dragging colors.

Parameters
color	for icon

QgsColorWidget::QgsColorWidget(QWidget* parent = nullptr, ColorComponent component = Multiple)

Construct a new color widget.

Parameters
parent	parent QWidget for the widget
component	color component the widget alters

QColor QgsColorWidget::color() const

Returns the current color for the widget.

Returns	current widget color

ColorComponent QgsColorWidget::component() const

Returns the color component which the widget controls.

Returns	color component for widget

int QgsColorWidget::componentValue() const

Returns the current value of the widget's color component.

Returns	value of color component, or -1 if widget has multiple components or an invalid color set

void QgsColorWidget::colorChanged(const QColor& color) signal

Emitted when the widget's color changes.

Parameters
color	new widget color

void QgsColorWidget::hovered() signal

Emitted when mouse hovers over widget.

void QgsColorWidget::setColor(const QColor& color, bool emitSignals = false) virtual public slot

Sets the color for the widget.

Parameters
color	widget color
emitSignals	set to true to emit the colorChanged signal after setting color

void QgsColorWidget::setComponent(QgsColorWidget::ColorComponent component) virtual public slot

Sets the color component which the widget controls.

Parameters
component	color component for widget

void QgsColorWidget::setComponentValue(int value) virtual public slot

Alters the widget's color by setting the value for the widget's color component.

Parameters
value	value for widget's color component. This value is automatically clipped to the range of valid values for the color component.

static const QPixmap& QgsColorWidget::transparentBackground() protected

Generates a checkboard pattern pixmap for use as a background to transparent colors.

Returns	checkerboard pixmap

void QgsColorWidget::alterColor(QColor& color, QgsColorWidget::ColorComponent component, int newValue) const protected

Alters a color by modifiying the value of a specific color component.

Parameters
color	color to alter
component	color component to alter
newValue	new value of color component. Values are automatically clipped to a valid range for the color component.

int QgsColorWidget::componentRange() const protected

Returns the range of valid values for the color widget's component.

Returns	maximum value allowed for color component, or -1 if widget has multiple components

int QgsColorWidget::componentRange(ColorComponent component) const protected

Returns the range of valid values a color component.

Returns	maximum value allowed for color component

int QgsColorWidget::componentValue(ColorComponent component) const protected

Returns the value of a component of the widget's current color.

Parameters
component	color component to return
Returns	value of color component, or -1 if widget has an invalid color set

This method correctly handles hue values when the color has an ambiguous hue (e.g., black or white shades)

int QgsColorWidget::hue() const protected

Returns the hue for the widget.

Returns	explicitly set hue for widget

This may differ from the hue for the QColor returned by color(), as QColor returns a hue of -1 if the color's hue is ambiguous (e.g., if the saturation is zero).

Variable documentation

int QgsColorWidget::mExplicitHue protected

QColor wipes the hue information when it is ambiguous (e.g., for saturation = 0).

So the hue is stored in mExplicit hue to keep it around, as it is useful when modifying colors