Class: QgsColorWidget

A base class for interactive color widgets.

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

Class Hierarchy

Base classes

QWidget
QObject
QPaintDevice

Subclasses

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

Enums

ComponentUnit

Specified the color component unit

Methods

color	Returns the current color for the widget
colorSpec	Returns color widget type of color, either RGB, HSV, CMYK, or Invalid if this component value is Multiple or Alpha
component	Returns the color component which the widget controls
componentRange	Returns the range of valid values for the color widget's component
componentValue	Returns the current value of the widget's color component
componentValueF	Returns the current value of the widget's color component
hue	Returns the hue for the widget.
hueF	Returns the hue for the widget.
transparentBackground	Generates a checkboard pattern pixmap for use as a background to transparent colors

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsColorWidget. See the FAQ for more details.

setColor	Sets the color for the widget
setComponent	Sets the color component which the widget controls
setComponentValue	Alters the widget's color by setting the value for the widget's color component
setComponentValueF	Alters the widget's color by setting the value for the widget's color component

Static Methods

alterColor	Alters a color by modifying the value of a specific color component
alterColorF	Alters a color by modifying the value of a specific color component
componentUnit	Returns color component unit
createDragIcon	Create an icon for dragging colors

Signals

colorChanged	Emitted when the widget's color changes
hovered	Emitted when mouse hovers over widget.

Attributes

Alpha
Black
Blue
Cyan
Green
Hue
Magenta
Multiple
Red
Saturation
Value
Yellow

class qgis.gui.QgsColorWidget

Bases: QWidget

__init__(parent: QWidget | None = None, component: QgsColorWidget.ColorComponent = QgsColorWidget.Multiple)

Construct a new color widget.

Parameters:

• parent (Optional[QWidget] = None) – parent QWidget for the widget

• component (QgsColorWidget.ColorComponent = QgsColorWidget.Multiple) – color component the widget alters

Alpha = 7

Black = 11

Blue = 3

class ColorComponent

Bases: int

class ComponentUnit(*values)

Bases: IntEnum

Specified the color component unit

• Scaled0to255: Values in the range 0-255

• Percent: Percent values in the range 0-100

• Degree: Degree values in the range 0-359

Degree = 2

Percent = 1

Scaled0to255 = 0

Cyan = 8

Green = 2

Hue = 4

Magenta = 9

Multiple = 0

Red = 1

Saturation = 5

Value = 6

Yellow = 10

static alterColor(color: QColor | Qt.GlobalColor, component: QgsColorWidget.ColorComponent, newValue: int)

Alters a color by modifying the value of a specific color component

Parameters:

• color (Union[QColor, Qt.GlobalColor]) – color to alter

• component (QgsColorWidget.ColorComponent) – color component to alter

• newValue (int) – new value of color component in the range between 0 and the value returned by componentRange(). Values are automatically clipped to a valid range for the color component.

Deprecated since version 3.40: Use alterColorF() instead.

static alterColorF(color: QColor | Qt.GlobalColor, component: QgsColorWidget.ColorComponent, newValue: float)

Alters a color by modifying the value of a specific color component

Parameters:

• color (Union[QColor, Qt.GlobalColor]) – color to alter

• component (QgsColorWidget.ColorComponent) – color component to alter

• newValue (float) – new value of color component in the range between 0 and the value returned by componentRange(). Values are automatically clipped to range 0.0-1.0

Added in version 3.40.

color(self) → QColor

Returns the current color for the widget

Return type:

QColor

Returns:

current widget color

See also

setColor()

signal colorChanged(color: QColor)

Emitted when the widget’s color changes

Parameters:

color (QColor) – new widget color

colorSpec(self) → QColor.Spec

Returns color widget type of color, either RGB, HSV, CMYK, or Invalid if this component value is Multiple or Alpha

Return type:

QColor.Spec

colorSpec(component: QgsColorWidget.ColorComponent) → QColor.Spec

Returns component type of color, either RGB, HSV, CMYK, or Invalid if component value is Multiple or Alpha

Parameters:

component (QgsColorWidget.ColorComponent)

Return type:

QColor.Spec

component(self) → QgsColorWidget.ColorComponent

Returns the color component which the widget controls

Return type:

QgsColorWidget.ColorComponent

Returns:

color component for widget

See also

setComponent()

componentRange(self) → int

Returns the range of valid values for the color widget’s component

Return type:

int

Returns:

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

componentRange(component: QgsColorWidget.ColorComponent) → int

Returns the range of valid values a color component

Return type:

int

Returns:

maximum value allowed for color component

Parameters:

component (QgsColorWidget.ColorComponent)

static componentUnit(component: QgsColorWidget.ColorComponent) → QgsColorWidget.ComponentUnit

Returns color component unit

Parameters:

component (QgsColorWidget.ColorComponent)

Return type:

QgsColorWidget.ComponentUnit

componentValue(self) → int

Returns the current value of the widget’s color component

Return type:

int

Returns:

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

See also

setComponentValue()

See also

component()

Deprecated since version 3.40: Use componentValueF() instead.

componentValue(self, component: QgsColorWidget.ColorComponent) → int

Returns the value of a component of the widget’s current color. This method correctly handles hue values when the color has an ambiguous hue (e.g., black or white shades)

Parameters:

component (QgsColorWidget.ColorComponent) – color component to return

Return type:

int

Returns:

value of color component in the range between 0 and the value returned by componentRange(), or -1 if widget has an invalid color set

See also

hue()

Deprecated since version 3.40: Use componentValueF() instead.

componentValueF(self) → float

Returns the current value of the widget’s color component

Return type:

float

Returns:

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

See also

setComponentValueF()

See also

component()

Added in version 3.40.

componentValueF(self, component: QgsColorWidget.ColorComponent) → float

Returns the value of a component of the widget’s current color. This method correctly handles hue values when the color has an ambiguous hue (e.g., black or white shades)

Parameters:

component (QgsColorWidget.ColorComponent) – color component to return

Return type:

float

Returns:

value of color component in the range 0-1.0, or -1 if widget has an invalid color set

See also

hue()

Added in version 3.40.

static createDragIcon(color: QColor | Qt.GlobalColor) → QPixmap

Create an icon for dragging colors

Parameters:

color (Union[QColor, Qt.GlobalColor]) – for icon

Return type:

QPixmap

signal hovered

Emitted when mouse hovers over widget.

hue(self) → int

Returns the hue for the 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).

Return type:

int

Returns:

explicitly set hue for widget in the range 0-359

Deprecated since version 3.40: Use hueF() instead.

hueF(self) → float

Returns the hue for the 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).

Return type:

float

Returns:

explicitly set hue for widget in the range 0-1.0

Added in version 3.40.

virtual setColor(self, color: QColor | Qt.GlobalColor, emitSignals: bool = False)

Sets the color for the widget

Parameters:

• color (Union[QColor, Qt.GlobalColor]) – widget color

• emitSignals (bool = False) – set to True to emit the colorChanged signal after setting color

See also

color()

virtual setComponent(self, component: QgsColorWidget.ColorComponent)

Sets the color component which the widget controls

Parameters:

component (QgsColorWidget.ColorComponent) – color component for widget

See also

component()

virtual setComponentValue(self, value: int)

Alters the widget’s color by setting the value for the widget’s color component

Parameters:

value (int) – value for widget’s color component in the range between 0 and the value returned by componentRange(). This value is automatically clipped to the range of valid values for the color component.

See also

componentValue()

See also

setComponent()

Note

this method has no effect if the widget is set to the QgsColorWidget.Multiple component

Deprecated since version 3.40: Use setComponentValueF() instead.

virtual setComponentValueF(self, value: float)

Alters the widget’s color by setting the value for the widget’s color component

Parameters:

value (float) – value for widget’s color component in the range 0.0-1.0. This value is automatically clipped to the range 0.0-1.0.

See also

componentValue()

See also

setComponent()

Note

this method has no effect if the widget is set to the QgsColorWidget.Multiple component

Added in version 3.40.

transparentBackground() → QPixmap

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

Return type:

QPixmap

Returns:

checkerboard pixmap