QGIS API Documentation 3.39.0-Master (3783037d301)
Loading...
Searching...
No Matches
Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends | List of all members
QgsColorWidget Class Reference

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

#include <qgscolorwidgets.h>

Inheritance diagram for QgsColorWidget:
Inheritance graph
[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 38 of file qgscolorwidgets.h.

Member Enumeration Documentation

◆ 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 47 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 66 of file qgscolorwidgets.h.

Constructor & Destructor Documentation

◆ QgsColorWidget()

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

Construct a new color widget.

Parameters
parentparent QWidget for the widget
componentcolor component the widget alters

Definition at line 58 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
colorcolor to alter
componentcolor component to alter
newValuenew 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 208 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
colorcolor to alter
componentcolor component to alter
newValuenew 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 215 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 374 of file qgscolorwidgets.cpp.

◆ colorChanged

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

Emitted when the widget's color changes.

Parameters
colornew 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 303 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 278 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 93 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 166 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 171 of file qgscolorwidgets.cpp.

◆ componentUnit()

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

Returns color component unit.

Definition at line 96 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 66 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
componentcolor 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 121 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 71 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
componentcolor 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 126 of file qgscolorwidgets.cpp.

◆ createDragIcon()

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

Create an icon for dragging colors.

Parameters
colorfor icon

Definition at line 76 of file qgscolorwidgets.cpp.

◆ dragEnterEvent()

void QgsColorWidget::dragEnterEvent ( QDragEnterEvent *  e)
overrideprotected

Definition at line 318 of file qgscolorwidgets.cpp.

◆ dropEvent()

void QgsColorWidget::dropEvent ( QDropEvent *  e)
overrideprotected

Definition at line 331 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 191 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 196 of file qgscolorwidgets.cpp.

◆ mouseMoveEvent()

void QgsColorWidget::mouseMoveEvent ( QMouseEvent *  e)
overrideprotected

Definition at line 355 of file qgscolorwidgets.cpp.

◆ mousePressEvent()

void QgsColorWidget::mousePressEvent ( QMouseEvent *  e)
overrideprotected

Definition at line 362 of file qgscolorwidgets.cpp.

◆ mouseReleaseEvent()

void QgsColorWidget::mouseReleaseEvent ( QMouseEvent *  e)
overrideprotected

Definition at line 368 of file qgscolorwidgets.cpp.

◆ setColor

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

Sets the color for the widget.

Parameters
colorwidget color
emitSignalsset to true to emit the colorChanged signal after setting color
See also
color

Reimplemented in QgsColorSliderWidget, and QgsColorTextWidget.

Definition at line 424 of file qgscolorwidgets.cpp.

◆ setComponent

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

Sets the color component which the widget controls.

Parameters
componentcolor component for widget
See also
component

Reimplemented in QgsColorBox, and QgsColorSliderWidget.

Definition at line 379 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
valuevalue 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 390 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
valuevalue 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 395 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 308 of file qgscolorwidgets.cpp.

Friends And Related Symbol Documentation

◆ TestQgsCompoundColorWidget

friend class TestQgsCompoundColorWidget
friend

Definition at line 288 of file qgscolorwidgets.h.

Member Data Documentation

◆ mComponent

ColorComponent QgsColorWidget::mComponent
protected

Definition at line 185 of file qgscolorwidgets.h.

◆ mCurrentColor

QColor QgsColorWidget::mCurrentColor
protected

Definition at line 183 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 191 of file qgscolorwidgets.h.


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