A base class for interactive color widgets. More...

#include <qgscolorwidgets.h>

Inheritance diagram for QgsColorWidget:

[legend]

Public Types
enum	ColorComponent { Multiple = 0 , Red , Green , Blue , Hue , Saturation , Value , Alpha , Cyan , Magenta , Yellow , Black }
	Specifies the color component which the widget alters. More...
enum class	ComponentUnit { Scaled0to255 , Percent , Degree }
	Specified the color component unit. More...

Public Slots
virtual void	setColor (const QColor &color, bool emitSignals=false)
	Sets the color for the widget.
virtual void	setComponent (QgsColorWidget::ColorComponent component)
	Sets the color component which the widget controls.
virtual Q_DECL_DEPRECATED void	setComponentValue (int value)
	Alters the widget's color by setting the value for the widget's color component.
virtual void	setComponentValueF (float value)
	Alters the widget's color by setting the value for 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 Member Functions
	QgsColorWidget (QWidget *parent=nullptr, ColorComponent component=Multiple)
	Construct a new color widget.
QColor	color () const
	Returns the current color for the widget.
ColorComponent	component () const
	Returns the color component which the widget controls.
Q_DECL_DEPRECATED int	componentValue () const
	Returns the current value of the widget's color component.
float	componentValueF () const
	Returns the current value of the widget's color component.

Static Public Member Functions
static ComponentUnit	componentUnit (ColorComponent component)
	Returns color component unit.
static QPixmap	createDragIcon (const QColor &color)
	Create an icon for dragging colors.

Protected Member Functions
QColor::Spec	colorSpec () const
	Returns color widget type of color, either RGB, HSV, CMYK, or Invalid if this component value is Multiple or Alpha.
int	componentRange () const
	Returns the range of valid values for the color widget's component.
Q_DECL_DEPRECATED int	componentValue (ColorComponent component) const
	Returns the value of a component of the widget's current color.
float	componentValueF (ColorComponent component) const
	Returns the value of a component of the widget's current color.
void	dragEnterEvent (QDragEnterEvent *e) override
void	dropEvent (QDropEvent *e) override
Q_DECL_DEPRECATED int	hue () const
	Returns the hue for the widget.
float	hueF () const
	Returns the hue for the widget.
void	mouseMoveEvent (QMouseEvent *e) override
void	mousePressEvent (QMouseEvent *e) override
void	mouseReleaseEvent (QMouseEvent *e) override

Static Protected Member Functions
static Q_DECL_DEPRECATED void	alterColor (QColor &color, QgsColorWidget::ColorComponent component, int newValue)
	Alters a color by modifying the value of a specific color component.
static void	alterColorF (QColor &color, QgsColorWidget::ColorComponent component, float newValue)
	Alters a color by modifying the value of a specific color component.
static QColor::Spec	colorSpec (QgsColorWidget::ColorComponent component)
	Returns component type of color, either RGB, HSV, CMYK, or Invalid if component value is Multiple or Alpha.
static int	componentRange (ColorComponent component)
	Returns the range of valid values a color component.
static const QPixmap &	transparentBackground ()
	Generates a checkboard pattern pixmap for use as a background to transparent colors.

Protected Attributes
ColorComponent	mComponent
QColor	mCurrentColor
float	mExplicitHue = 0
	QColor wipes the hue information when it is ambiguous (e.g., for saturation = 0).

Friends
class	TestQgsCompoundColorWidget

Detailed Description

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

Definition at line 43 of file qgscolorwidgets.h.

Member Enumeration Documentation

◆ ColorComponent

enum QgsColorWidget::ColorComponent

Specifies the color component which the widget alters.

Enumerator
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.
Cyan	Cyan component (based on CMYK model) of color.
Magenta	Magenta component (based on CMYK model) of color.
Yellow	Yellow component (based on CMYK model) of color.
Black	Black component (based on CMYK model) of color.

Definition at line 52 of file qgscolorwidgets.h.

◆ ComponentUnit

enum class QgsColorWidget::ComponentUnit

strong

Specified the color component unit.

Enumerator
Scaled0to255	Values in the range 0-255.
Percent	Percent values in the range 0-100.
Degree	Degree values in the range 0-359.

Definition at line 71 of file qgscolorwidgets.h.

Constructor & Destructor Documentation

◆ QgsColorWidget()

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

Definition at line 61 of file qgscolorwidgets.cpp.

Member Function Documentation

◆ alterColor()

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

staticprotected

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

Parameters

color	color to alter
component	color component to alter
newValue	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: QGIS 3.40. Use alterColorF() instead.

Definition at line 211 of file qgscolorwidgets.cpp.

◆ alterColorF()

void QgsColorWidget::alterColorF	(	QColor &	color,
		QgsColorWidget::ColorComponent	component,
		float	newValue )

staticprotected

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

Parameters

color	color to alter
component	color component to alter
newValue	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

Since: QGIS 3.40

Definition at line 218 of file qgscolorwidgets.cpp.

◆ color()

QColor QgsColorWidget::color ( ) const

Returns the current color for the widget.

Returns: current widget color

See also: setColor

Definition at line 377 of file qgscolorwidgets.cpp.

◆ colorChanged

void QgsColorWidget::colorChanged ( const QColor & color )

signal

Emitted when the widget's color changes.

Parameters

color new widget color

◆ colorSpec() [1/2]

QColor::Spec QgsColorWidget::colorSpec ( ) const

protected

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

Definition at line 306 of file qgscolorwidgets.cpp.

◆ colorSpec() [2/2]

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

staticprotected

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

Definition at line 281 of file qgscolorwidgets.cpp.

◆ component()

ColorComponent QgsColorWidget::component ( ) const

inline

Returns the color component which the widget controls.

Returns: color component for widget

See also: setComponent

Definition at line 98 of file qgscolorwidgets.h.

◆ componentRange() [1/2]

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

Definition at line 169 of file qgscolorwidgets.cpp.

◆ componentRange() [2/2]

int QgsColorWidget::componentRange ( const QgsColorWidget::ColorComponent component )

staticprotected

Returns the range of valid values a color component.

Returns: maximum value allowed for color component

Definition at line 174 of file qgscolorwidgets.cpp.

◆ componentUnit()

QgsColorWidget::ComponentUnit QgsColorWidget::componentUnit ( ColorComponent component )

static

Returns color component unit.

Definition at line 99 of file qgscolorwidgets.cpp.

◆ componentValue() [1/2]

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

See also: setComponentValue; component

Deprecated: QGIS 3.40. Use componentValueF() instead.

Definition at line 69 of file qgscolorwidgets.cpp.

◆ componentValue() [2/2]

int QgsColorWidget::componentValue ( const QgsColorWidget::ColorComponent component ) const

protected

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 color component to return

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: QGIS 3.40. Use componentValueF() instead.

Definition at line 124 of file qgscolorwidgets.cpp.

◆ componentValueF() [1/2]

float QgsColorWidget::componentValueF ( ) 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

See also: setComponentValueF; component

Since: QGIS 3.40

Definition at line 74 of file qgscolorwidgets.cpp.

◆ componentValueF() [2/2]

float QgsColorWidget::componentValueF ( const QgsColorWidget::ColorComponent component ) const

protected

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 color component to return

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

See also: hue()

Since: QGIS 3.40

Definition at line 129 of file qgscolorwidgets.cpp.

◆ createDragIcon()

QPixmap QgsColorWidget::createDragIcon ( const QColor & color )

static

Create an icon for dragging colors.

Parameters

color for icon

Definition at line 79 of file qgscolorwidgets.cpp.

◆ dragEnterEvent()

void QgsColorWidget::dragEnterEvent ( QDragEnterEvent * e )

overrideprotected

Definition at line 321 of file qgscolorwidgets.cpp.

◆ dropEvent()

void QgsColorWidget::dropEvent ( QDropEvent * e )

overrideprotected

Definition at line 334 of file qgscolorwidgets.cpp.

◆ hovered

void QgsColorWidget::hovered ( )

signal

Emitted when mouse hovers over widget.

◆ hue()

int QgsColorWidget::hue ( ) const

protected

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

Returns: explicitly set hue for widget in the range 0-359

Deprecated: QGIS 3.40. Use hueF() instead.

Definition at line 194 of file qgscolorwidgets.cpp.

◆ hueF()

float QgsColorWidget::hueF ( ) const

protected

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

Returns: explicitly set hue for widget in the range 0-1.0

Since: QGIS 3.40

Definition at line 199 of file qgscolorwidgets.cpp.

◆ mouseMoveEvent()

void QgsColorWidget::mouseMoveEvent ( QMouseEvent * e )

overrideprotected

Definition at line 358 of file qgscolorwidgets.cpp.

◆ mousePressEvent()

void QgsColorWidget::mousePressEvent ( QMouseEvent * e )

overrideprotected

Definition at line 365 of file qgscolorwidgets.cpp.

◆ mouseReleaseEvent()

void QgsColorWidget::mouseReleaseEvent ( QMouseEvent * e )

overrideprotected

Definition at line 371 of file qgscolorwidgets.cpp.

◆ setColor

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

virtualslot

Sets the color for the widget.

Parameters

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

See also: color

Reimplemented in QgsColorSliderWidget, and QgsColorTextWidget.

Definition at line 427 of file qgscolorwidgets.cpp.

◆ setComponent

void QgsColorWidget::setComponent ( QgsColorWidget::ColorComponent component )

virtualslot

Sets the color component which the widget controls.

Parameters

component color component for widget

See also: component

Reimplemented in QgsColorBox, and QgsColorSliderWidget.

Definition at line 382 of file qgscolorwidgets.cpp.

◆ setComponentValue

void QgsColorWidget::setComponentValue ( int value )

virtualslot

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

Parameters

value 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; setComponent

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

Deprecated: QGIS 3.40. Use setComponentValueF() instead.

Definition at line 393 of file qgscolorwidgets.cpp.

◆ setComponentValueF

void QgsColorWidget::setComponentValueF ( float value )

virtualslot

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

Parameters

value 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; setComponent

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

Since: QGIS 3.40

Reimplemented in QgsColorSliderWidget.

Definition at line 398 of file qgscolorwidgets.cpp.

◆ transparentBackground()

const QPixmap & QgsColorWidget::transparentBackground ( )

staticprotected

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

Returns: checkerboard pixmap

Definition at line 311 of file qgscolorwidgets.cpp.

◆ TestQgsCompoundColorWidget

friend class TestQgsCompoundColorWidget

friend

Definition at line 292 of file qgscolorwidgets.h.

Member Data Documentation

◆ mComponent

ColorComponent QgsColorWidget::mComponent

protected

Definition at line 189 of file qgscolorwidgets.h.

◆ mCurrentColor

QColor QgsColorWidget::mCurrentColor

protected

Definition at line 187 of file qgscolorwidgets.h.

◆ mExplicitHue

float QgsColorWidget::mExplicitHue = 0

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

Definition at line 195 of file qgscolorwidgets.h.

The documentation for this class was generated from the following files:

/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/gui/qgscolorwidgets.h
/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/gui/qgscolorwidgets.cpp

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ ColorComponent

◆ ComponentUnit

Constructor & Destructor Documentation

◆ QgsColorWidget()

Member Function Documentation

◆ alterColor()

◆ alterColorF()

◆ color()

◆ colorChanged

◆ colorSpec() [1/2]

◆ colorSpec() [2/2]

◆ component()

◆ componentRange() [1/2]

◆ componentRange() [2/2]

◆ componentUnit()

◆ componentValue() [1/2]

◆ componentValue() [2/2]

◆ componentValueF() [1/2]

◆ componentValueF() [2/2]

◆ createDragIcon()

◆ dragEnterEvent()

◆ dropEvent()

◆ hovered

◆ hue()

◆ hueF()

◆ mouseMoveEvent()

◆ mousePressEvent()

◆ mouseReleaseEvent()

◆ setColor

◆ setComponent

◆ setComponentValue

◆ setComponentValueF

◆ transparentBackground()

Friends And Related Symbol Documentation

◆ TestQgsCompoundColorWidget

Member Data Documentation

◆ mComponent

◆ mCurrentColor

◆ mExplicitHue