A cross platform button subclass for selecting colors. More...

#include <qgscolorbutton.h>

Inheritance diagram for QgsColorButton:

Public Types
enum	Behavior { ShowDialog = 0 , SignalOnly }
	Specifies the behavior when the button is clicked. More...

Public Slots
void	activatePicker ()
	Activates the color picker tool, which allows for sampling a color from anywhere on the screen.

void	copyColor ()
	Copies the current color to the clipboard.

void	pasteColor ()
	Pastes a color from the clipboard to the color button.

void	setButtonBackground (const QColor &color=QColor())
	Sets the background pixmap for the button based upon color and transparency.

void	setColor (const QColor &color)
	Sets the current color for the button.

void	setToDefaultColor ()
	Sets color to the button's default color, if set.

void	setToNoColor ()
	Sets color to a totally transparent color.

void	setToNull ()
	Sets color to null.

void	unlink ()
	Unlinks the button from a project color.

Signals
void	cleared ()
	Emitted when the color is cleared (set to null).

void	colorChanged (const QColor &color)
	Emitted whenever a new color is set for the button.

void	colorClicked (const QColor &color)
	Emitted when the button is clicked, if the button's behavior is set to SignalOnly.

void	unlinked ()
	Emitted when the color is unlinked, e.g.

Public Member Functions
	QgsColorButton (QWidget parent=nullptr, const QString &cdt=QString(), QgsColorSchemeRegistry registry=nullptr)
	Construct a new color ramp button.

bool	allowOpacity () const
	Returns whether opacity modification (transparency) is permitted for the color.

Behavior	behavior () const
	Returns the behavior for when the button is clicked.

QColor	color () const
	Returns the currently selected color.

QString	colorDialogTitle () const
	Returns the title for the color chooser dialog window.

QgsColorSchemeRegistry *	colorSchemeRegistry ()
	Returns the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.

QString	context () const
	Returns the context string for the color button.

QColor	defaultColor () const
	Returns the default color for the button, which is shown in the button's drop-down menu for the "default color" option.

bool	isNull () const
	Returns `true` if the current color is null.

QString	linkedProjectColorName () const
	Returns the linked project color name, if set.

void	linkToProjectColor (const QString &name)
	Sets the button to link to an existing project color, by color name.

QSize	minimumSizeHint () const override

QString	noColorString () const
	Returns the string used for the "no color" option in the button's drop-down menu.

void	setAllowOpacity (bool allowOpacity)
	Sets whether opacity modification (transparency) is permitted for the color.

void	setBehavior (Behavior behavior)
	Sets the behavior for when the button is clicked.

void	setColorDialogTitle (const QString &title)
	Set the title for the color chooser dialog window.

void	setColorSchemeRegistry (QgsColorSchemeRegistry *registry)
	Sets the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.

void	setContext (const QString &context)
	Sets the context string for the color button.

void	setDefaultColor (const QColor &color)
	Sets the default color for the button, which is shown in the button's drop-down menu for the "default color" option.

void	setNoColorString (const QString &noColorString)
	Sets the string to use for the "no color" option in the button's drop-down menu.

void	setShowMenu (bool showMenu)
	Sets whether the drop-down menu should be shown for the button.

void	setShowNoColor (const bool showNoColorOption)
	Sets whether the "no color" option should be shown in the button's drop-down menu.

void	setShowNull (bool showNull, const QString &nullString=QString())
	Sets whether a set to null (clear) option is shown in the button's drop-down menu.

bool	showMenu () const
	Returns whether the drop-down menu is shown for the button.

bool	showNoColor () const
	Returns whether the "no color" option is shown in the button's drop-down menu.

bool	showNull () const
	Returns whether the set to null (clear) option is shown in the button's drop-down menu.

QSize	sizeHint () const override

Static Public Member Functions
static QPixmap	createMenuIcon (const QColor &color, bool showChecks=true)
	Creates an icon for displaying a color in a drop-down menu.

Protected Member Functions
void	changeEvent (QEvent *e) override

void	dragEnterEvent (QDragEnterEvent *e) override
	Reimplemented to accept dragged colors.

void	dragLeaveEvent (QDragLeaveEvent *e) override
	Reimplemented to reset button appearance after drag leave.

void	dropEvent (QDropEvent *e) override
	Reimplemented to accept dropped colors.

bool	event (QEvent *e) override

void	keyPressEvent (QKeyEvent *e) override
	Reimplemented to allow canceling color pick via keypress, and sample via space bar press.

void	mouseMoveEvent (QMouseEvent *e) override
	Reimplemented to allow dragging colors from button.

void	mousePressEvent (QMouseEvent *e) override
	Reimplemented to detect right mouse button clicks on the color button and allow dragging colors.

void	mouseReleaseEvent (QMouseEvent *e) override
	Reimplemented to allow color picking.

void	resizeEvent (QResizeEvent *event) override

void	showEvent (QShowEvent *e) override

void	wheelEvent (QWheelEvent *event) override

Static Protected Member Functions
static const QPixmap &	transparentBackground ()
	Returns a checkboard pattern pixmap for use as a background to transparent colors.

Properties
bool	allowOpacity

Behavior	behavior

QColor	color

QString	colorDialogTitle

QString	context

QColor	defaultColor

QString	noColorString

bool	showMenu

bool	showNoColor

Friends
class	QgsColorTooltip

Detailed Description

A cross platform button subclass for selecting colors.

Will open a color chooser dialog when clicked. Offers live updates to button from color chooser dialog. An attached drop-down menu allows for copying and pasting colors, picking colors from the screen, and selecting colors from color swatch grids.

Definition at line 34 of file qgscolorbutton.h.

Member Enumeration Documentation

◆ Behavior

enum QgsColorButton::Behavior

Specifies the behavior when the button is clicked.

Enumerator
ShowDialog	Show a color picker dialog when clicked.
SignalOnly	Emit colorClicked signal only, no dialog.

Definition at line 63 of file qgscolorbutton.h.

Constructor & Destructor Documentation

◆ QgsColorButton()

QgsColorButton::QgsColorButton	(	QWidget *	parent = `nullptr`,
		const QString &	cdt = `QString()`,
		QgsColorSchemeRegistry *	registry = `nullptr`
	)

Construct a new color ramp button.

Use parent to attach a parent QWidget to the dialog. Use cdt string to define the title to show in the color ramp dialog Use a color scheme registry for color swatch grids to show in the drop-down menu. If not specified, the button will use the global color scheme registry instead

Definition at line 44 of file qgscolorbutton.cpp.

Member Function Documentation

◆ activatePicker

void QgsColorButton::activatePicker ( )

slot

Activates the color picker tool, which allows for sampling a color from anywhere on the screen.

Definition at line 767 of file qgscolorbutton.cpp.

◆ allowOpacity()

bool QgsColorButton::allowOpacity ( ) const

inline

Returns whether opacity modification (transparency) is permitted for the color.

Returns: true if opacity modification is allowed

See also: setAllowOpacity()

Definition at line 103 of file qgscolorbutton.h.

◆ behavior()

Behavior QgsColorButton::behavior ( ) const

inline

Returns the behavior for when the button is clicked.

Returns: behavior when button is clicked

See also: setBehavior

Definition at line 147 of file qgscolorbutton.h.

◆ changeEvent()

void QgsColorButton::changeEvent ( QEvent * e )

overrideprotected

Definition at line 587 of file qgscolorbutton.cpp.

◆ cleared

void QgsColorButton::cleared ( )

signal

Emitted when the color is cleared (set to null).

See also: setToNull()

Since: QGIS 3.12

◆ color()

QColor QgsColorButton::color ( ) const

Returns the currently selected color.

Returns: currently selected color

See also: setColor

Definition at line 779 of file qgscolorbutton.cpp.

◆ colorChanged

void QgsColorButton::colorChanged ( const QColor & color )

signal

Emitted whenever a new color is set for the button.

The color is always valid. In case the new color is the same no signal is emitted, to avoid infinite loops.

Parameters

color New color

◆ colorClicked

void QgsColorButton::colorClicked ( const QColor & color )

signal

Emitted when the button is clicked, if the button's behavior is set to SignalOnly.

Parameters

color button color

See also: setBehavior; behavior

◆ colorDialogTitle()

QString QgsColorButton::colorDialogTitle ( ) const

Returns the title for the color chooser dialog window.

Returns: title for the color chooser dialog

See also: setColorDialogTitle

Definition at line 797 of file qgscolorbutton.cpp.

◆ colorSchemeRegistry()

QgsColorSchemeRegistry * QgsColorButton::colorSchemeRegistry ( )

inline

Returns the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.

Returns: color scheme registry for the button. If returned value is 0 then all color swatch grids are hidden from the button's drop-down menu.

See also: setColorSchemeRegistry

Definition at line 266 of file qgscolorbutton.h.

◆ context()

QString QgsColorButton::context ( ) const

inline

Returns the context string for the color button.

The context string is passed to all color swatch grids shown in the button's drop-down menu, to allow them to customize their display colors based on the context.

Returns: context string for the color button's color swatch grids

See also: setContext

Definition at line 248 of file qgscolorbutton.h.

◆ copyColor

void QgsColorButton::copyColor ( )

slot

Copies the current color to the clipboard.

See also: pasteColor

Definition at line 747 of file qgscolorbutton.cpp.

◆ createMenuIcon()

QPixmap QgsColorButton::createMenuIcon	(	const QColor &	color,
		bool	showChecks = `true`
	)

static

Creates an icon for displaying a color in a drop-down menu.

If showChecks set to true, then a checkboard pattern will be shown behind semi-transparent colors.

Since: QGIS 3.6

Definition at line 423 of file qgscolorbutton.cpp.

◆ defaultColor()

QColor QgsColorButton::defaultColor ( ) const

inline

Returns the default color for the button, which is shown in the button's drop-down menu for the "default color" option.

Returns: default color for the button. Returns an invalid QColor if the default color option is disabled.

See also: setDefaultColor

Definition at line 165 of file qgscolorbutton.h.

◆ dragEnterEvent()

void QgsColorButton::dragEnterEvent ( QDragEnterEvent * e )

overrideprotected

Reimplemented to accept dragged colors.

Definition at line 345 of file qgscolorbutton.cpp.

◆ dragLeaveEvent()

void QgsColorButton::dragLeaveEvent ( QDragLeaveEvent * e )

overrideprotected

Reimplemented to reset button appearance after drag leave.

Definition at line 363 of file qgscolorbutton.cpp.

◆ dropEvent()

void QgsColorButton::dropEvent ( QDropEvent * e )

overrideprotected

Reimplemented to accept dropped colors.

Definition at line 370 of file qgscolorbutton.cpp.

◆ event()

bool QgsColorButton::event ( QEvent * e )

overrideprotected

Definition at line 170 of file qgscolorbutton.cpp.

◆ isNull()

bool QgsColorButton::isNull ( ) const

Returns true if the current color is null.

See also: setShowNull(); showNull()

Definition at line 833 of file qgscolorbutton.cpp.

◆ keyPressEvent()

void QgsColorButton::keyPressEvent ( QKeyEvent * e )

overrideprotected

Reimplemented to allow canceling color pick via keypress, and sample via space bar press.

Definition at line 332 of file qgscolorbutton.cpp.

◆ linkedProjectColorName()

QString QgsColorButton::linkedProjectColorName ( ) const

inline

Returns the linked project color name, if set.

See also: linkToProjectColor()

Since: QGIS 3.6

Definition at line 290 of file qgscolorbutton.h.

◆ linkToProjectColor()

void QgsColorButton::linkToProjectColor ( const QString & name )

Sets the button to link to an existing project color, by color name.

This changes the behavior of the button to a "linked" mode. Specifically, the button will show the linked color and respond to changes in the project color scheme by refreshing the displayed color automatically. Additionally, the button's menu will show items specific to linked color mode, including an option to "unlink" from the project color.

See also: linkedProjectColorName(); unlink()

Since: QGIS 3.6

Definition at line 838 of file qgscolorbutton.cpp.

◆ minimumSizeHint()

QSize QgsColorButton::minimumSizeHint ( ) const

override

Definition at line 77 of file qgscolorbutton.cpp.

◆ mouseMoveEvent()

void QgsColorButton::mouseMoveEvent ( QMouseEvent * e )

overrideprotected

Reimplemented to allow dragging colors from button.

Definition at line 241 of file qgscolorbutton.cpp.

◆ mousePressEvent()

void QgsColorButton::mousePressEvent ( QMouseEvent * e )

overrideprotected

Reimplemented to detect right mouse button clicks on the color button and allow dragging colors.

Definition at line 195 of file qgscolorbutton.cpp.

◆ mouseReleaseEvent()

void QgsColorButton::mouseReleaseEvent ( QMouseEvent * e )

overrideprotected

Reimplemented to allow color picking.

Definition at line 277 of file qgscolorbutton.cpp.

◆ noColorString()

QString QgsColorButton::noColorString ( ) const

inline

Returns the string used for the "no color" option in the button's drop-down menu.

Returns: string used for the "no color" menu option

See also: setNoColorString; showNoColor

Note: The "no color" option is only shown if the color button is set to show an alpha channel in the color dialog

Definition at line 230 of file qgscolorbutton.h.

◆ pasteColor

void QgsColorButton::pasteColor ( )

slot

Pastes a color from the clipboard to the color button.

If clipboard does not contain a valid color or string representation of a color, then no change is applied.

See also: copyColor

Definition at line 756 of file qgscolorbutton.cpp.

◆ resizeEvent()

void QgsColorButton::resizeEvent ( QResizeEvent * event )

overrideprotected

Definition at line 614 of file qgscolorbutton.cpp.

◆ setAllowOpacity()

void QgsColorButton::setAllowOpacity ( bool allowOpacity )

Sets whether opacity modification (transparency) is permitted for the color.

Defaults to false.

Parameters

allowOpacity set to true to allow opacity modification

See also: allowOpacity()

Definition at line 787 of file qgscolorbutton.cpp.

◆ setBehavior()

void QgsColorButton::setBehavior ( const QgsColorButton::Behavior behavior )

Sets the behavior for when the button is clicked.

The default behavior is to show a color picker dialog.

Parameters

behavior behavior when button is clicked

See also: behavior

Definition at line 812 of file qgscolorbutton.cpp.

◆ setButtonBackground

void QgsColorButton::setButtonBackground ( const QColor & color = QColor() )

slot

Sets the background pixmap for the button based upon color and transparency.

Call directly to update background after adding/removing QColorDialog::ShowAlphaChannel option but the color has not changed, i.e. setColor() wouldn't update button and you want the button to retain the set color's alpha component regardless

Parameters

color Color for button background. If no color is specified, the button's current color will be used

Definition at line 646 of file qgscolorbutton.cpp.

◆ setColor

void QgsColorButton::setColor ( const QColor & color )

slot

Sets the current color for the button.

Will emit a colorChanged signal if the color is different to the previous color.

Parameters

color new color for the button

See also: color

Definition at line 622 of file qgscolorbutton.cpp.

◆ setColorDialogTitle()

void QgsColorButton::setColorDialogTitle ( const QString & title )

Set the title for the color chooser dialog window.

Parameters

title Title for the color chooser dialog

See also: colorDialogTitle

Definition at line 792 of file qgscolorbutton.cpp.

◆ setColorSchemeRegistry()

void QgsColorButton::setColorSchemeRegistry ( QgsColorSchemeRegistry * registry )

inline

Sets the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.

Parameters

registry color scheme registry for the button. Set to 0 to hide all color swatch grids from the button's drop-down menu.

See also: colorSchemeRegistry

Definition at line 257 of file qgscolorbutton.h.

◆ setContext()

void QgsColorButton::setContext ( const QString & context )

inline

Sets the context string for the color button.

The context string is passed to all color swatch grids shown in the button's drop-down menu, to allow them to customize their display colors based on the context.

Parameters

context context string for the color button's color swatch grids

See also: context

Definition at line 239 of file qgscolorbutton.h.

◆ setDefaultColor()

void QgsColorButton::setDefaultColor ( const QColor & color )

Sets the default color for the button, which is shown in the button's drop-down menu for the "default color" option.

Parameters

color default color for the button. Set to an invalid QColor to disable the default color option.

See also: defaultColor

Definition at line 817 of file qgscolorbutton.cpp.

◆ setNoColorString()

void QgsColorButton::setNoColorString ( const QString & noColorString )

inline

Sets the string to use for the "no color" option in the button's drop-down menu.

Parameters

noColorString string to use for the "no color" menu option

See also: noColorString; setShowNoColor

Note: The "no color" option is only shown if the color button is set to show an alpha channel in the color dialog

Definition at line 197 of file qgscolorbutton.h.

◆ setShowMenu()

void QgsColorButton::setShowMenu ( bool showMenu )

Sets whether the drop-down menu should be shown for the button.

The default behavior is to show the menu.

Parameters

showMenu set to false to hide the drop-down menu

See also: showMenu

Definition at line 802 of file qgscolorbutton.cpp.

◆ setShowNoColor()

void QgsColorButton::setShowNoColor ( const bool showNoColorOption )

inline

Sets whether the "no color" option should be shown in the button's drop-down menu.

If selected, the "no color" option sets the color button's color to a totally transparent color.

Parameters

showNoColorOption set to true to show the no color option. This is disabled by default.

See also: showNoColor; setNoColorString

Note: The "no color" option is only shown if the color button is set to show an alpha channel in the color dialog

Definition at line 176 of file qgscolorbutton.h.

◆ setShowNull()

void QgsColorButton::setShowNull	(	bool	showNull,
		const QString &	nullString = `QString()`
	)

Sets whether a set to null (clear) option is shown in the button's drop-down menu.

Parameters

showNull	set to `true` to show a null option
nullString	translated string to use for the null option. If not set, a default "Clear Color" string will be used.

See also: showNull(); isNull()

Definition at line 822 of file qgscolorbutton.cpp.

◆ setToDefaultColor

void QgsColorButton::setToDefaultColor ( )

slot

Sets color to the button's default color, if set.

See also: setDefaultColor; defaultColor; setToNull()

Definition at line 148 of file qgscolorbutton.cpp.

◆ setToNoColor

void QgsColorButton::setToNoColor ( )

slot

Sets color to a totally transparent color.

Note: If the color button is not set to show an opacity channel in the color dialog then the color will not be changed.

See also: setToNull()

Definition at line 188 of file qgscolorbutton.cpp.

◆ setToNull

void QgsColorButton::setToNull ( )

slot

Sets color to null.

See also: setToDefaultColor(); setToNoColor(); cleared()

Definition at line 158 of file qgscolorbutton.cpp.

◆ showEvent()

void QgsColorButton::showEvent ( QShowEvent * e )

overrideprotected

Definition at line 608 of file qgscolorbutton.cpp.

◆ showMenu()

bool QgsColorButton::showMenu ( ) const

inline

Returns whether the drop-down menu is shown for the button.

Returns: true if drop-down menu is shown

See also: setShowMenu

Definition at line 132 of file qgscolorbutton.h.

◆ showNoColor()

bool QgsColorButton::showNoColor ( ) const

inline

Returns whether the "no color" option is shown in the button's drop-down menu.

If selected, the "no color" option sets the color button's color to a totally transparent color.

Returns: true if the no color option is shown.

See also: setShowNoColor; noColorString

Note: The "no color" option is only shown if the color button is set to show an alpha channel in the color dialog

Definition at line 187 of file qgscolorbutton.h.

◆ showNull()

bool QgsColorButton::showNull ( ) const

Returns whether the set to null (clear) option is shown in the button's drop-down menu.

See also: setShowNull(); isNull()

Definition at line 828 of file qgscolorbutton.cpp.

◆ sizeHint()

QSize QgsColorButton::sizeHint ( ) const

override

Definition at line 82 of file qgscolorbutton.cpp.

◆ transparentBackground()

const QPixmap & QgsColorButton::transparentBackground ( )

staticprotected

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

Definition at line 87 of file qgscolorbutton.cpp.

◆ unlink

void QgsColorButton::unlink ( )

slot

Unlinks the button from a project color.

See also: unlinked(); linkToProjectColor()

Since: QGIS 3.6

Definition at line 164 of file qgscolorbutton.cpp.

◆ unlinked

void QgsColorButton::unlinked ( )

signal

Emitted when the color is unlinked, e.g.

when it was previously set to link to a project color and is now no longer linked.

See also: unlink(); linkToProjectColor()

Since: QGIS 3.6

◆ wheelEvent()

void QgsColorButton::wheelEvent ( QWheelEvent * event )

overrideprotected

Definition at line 387 of file qgscolorbutton.cpp.

Friends And Related Symbol Documentation

◆ QgsColorTooltip

friend class QgsColorTooltip

friend

Definition at line 539 of file qgscolorbutton.h.

Property Documentation

◆ allowOpacity

bool QgsColorButton::allowOpacity

readwrite

Definition at line 50 of file qgscolorbutton.h.

◆ behavior

Behavior QgsColorButton::behavior

readwrite

Definition at line 52 of file qgscolorbutton.h.

◆ color

QColor QgsColorButton::color

readwrite

Definition at line 49 of file qgscolorbutton.h.

◆ colorDialogTitle

QString QgsColorButton::colorDialogTitle

readwrite

Definition at line 48 of file qgscolorbutton.h.

◆ context

QString QgsColorButton::context

readwrite

Definition at line 56 of file qgscolorbutton.h.

◆ defaultColor

QColor QgsColorButton::defaultColor

readwrite

Definition at line 53 of file qgscolorbutton.h.

◆ noColorString

QString QgsColorButton::noColorString

readwrite

Definition at line 55 of file qgscolorbutton.h.

◆ showMenu

bool QgsColorButton::showMenu

readwrite

Definition at line 51 of file qgscolorbutton.h.

◆ showNoColor

bool QgsColorButton::showNoColor

readwrite

Definition at line 54 of file qgscolorbutton.h.

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

/build/qgis-3.41.0+git20241201+3c143d501a8+99sid/src/gui/qgscolorbutton.h
/build/qgis-3.41.0+git20241201+3c143d501a8+99sid/src/gui/qgscolorbutton.cpp

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Properties

Friends

Detailed Description

Member Enumeration Documentation

◆ Behavior

Constructor & Destructor Documentation

◆ QgsColorButton()

Member Function Documentation

◆ activatePicker

◆ allowOpacity()

◆ behavior()

◆ changeEvent()

◆ cleared

◆ color()

◆ colorChanged

◆ colorClicked

◆ colorDialogTitle()

◆ colorSchemeRegistry()

◆ context()

◆ copyColor

◆ createMenuIcon()

◆ defaultColor()

◆ dragEnterEvent()

◆ dragLeaveEvent()

◆ dropEvent()

◆ event()

◆ isNull()

◆ keyPressEvent()

◆ linkedProjectColorName()

◆ linkToProjectColor()

◆ minimumSizeHint()

◆ mouseMoveEvent()

◆ mousePressEvent()

◆ mouseReleaseEvent()

◆ noColorString()

◆ pasteColor

◆ resizeEvent()

◆ setAllowOpacity()

◆ setBehavior()

◆ setButtonBackground

◆ setColor

◆ setColorDialogTitle()

◆ setColorSchemeRegistry()

◆ setContext()

◆ setDefaultColor()

◆ setNoColorString()

◆ setShowMenu()

◆ setShowNoColor()

◆ setShowNull()

◆ setToDefaultColor

◆ setToNoColor

◆ setToNull

◆ showEvent()

◆ showMenu()

◆ showNoColor()

◆ showNull()

◆ sizeHint()

◆ transparentBackground()

◆ unlink

◆ unlinked

◆ wheelEvent()

Friends And Related Symbol Documentation

◆ QgsColorTooltip

Property Documentation

◆ allowOpacity

◆ behavior

◆ color

◆ colorDialogTitle

◆ context

◆ defaultColor

◆ noColorString

◆ showMenu

◆ showNoColor