QgsColorButton class

A cross platform button subclass for selecting colors.

Reference

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.

Public types

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

Public static functions

static auto createMenuIcon(const QColor& color, bool showChecks = true) -> QPixmap: Creates an icon for displaying a color in a drop-down menu.

Constructors, destructors, conversion operators

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

Public functions

auto allowOpacity() const -> bool: Returns whether opacity modification (transparency) is permitted for the color.
auto behavior() const -> Behavior: Returns the behavior for when the button is clicked.
auto color() const -> QColor: Returns the currently selected color.
auto colorDialogTitle() const -> QString: Returns the title for the color chooser dialog window.
auto colorSchemeRegistry() -> QgsColorSchemeRegistry*: Returns the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.
auto context() const -> QString: Returns the context string for the color button.
auto defaultColor() const -> QColor: Returns the default color for the button, which is shown in the button's drop-down menu for the "default color" option.
auto isNull() const -> bool: Returns true if the current color is null.
auto noColorString() const -> QString: 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): Sets whether a set to null (clear) option is shown in the button's drop-down menu.
auto showMenu() const -> bool: Returns whether the drop-down menu is shown for the button.
auto showNoColor() const -> bool: Returns whether the "no color" option is shown in the button's drop-down menu.
auto showNull() const -> bool: Returns whether the set to null (clear) option is shown in the button's drop-down menu.

Signals

void colorChanged(const QColor& color): Is 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.

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.

Protected static functions

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

Protected functions

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

Enum documentation

enum QgsColorButton::Behavior

Specifies the behavior when the button is clicked.

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

Function documentation

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

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.

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

bool QgsColorButton::allowOpacity() const

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

Returns	true if opacity modification is allowed

Behavior QgsColorButton::behavior() const

Returns the behavior for when the button is clicked.

Returns	behavior when button is clicked

QColor QgsColorButton::color() const

Returns the currently selected color.

Returns	currently selected color

QString QgsColorButton::colorDialogTitle() const

Returns the title for the color chooser dialog window.

Returns	title for the color chooser dialog

QgsColorSchemeRegistry* QgsColorButton::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.

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.

QString QgsColorButton::context() const

Returns the context string for the color button.

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

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.

QColor QgsColorButton::defaultColor() const

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.

bool QgsColorButton::isNull() const

Returns true if the current color is null.

QString QgsColorButton::noColorString() const

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

void QgsColorButton::setAllowOpacity(bool allowOpacity)

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

Parameters
allowOpacity	set to true to allow opacity modification

Defaults to false.

void QgsColorButton::setBehavior(Behavior behavior)

Sets the behavior for when the button is clicked.

Parameters
behavior	behavior when button is clicked

The default behavior is to show a color picker dialog.

void QgsColorButton::setColorDialogTitle(const QString& title)

Set the title for the color chooser dialog window.

Parameters
title	Title for the color chooser dialog

void QgsColorButton::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.

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

void QgsColorButton::setContext(const QString& context)

Sets the context string for the color button.

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

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.

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.

void QgsColorButton::setNoColorString(const QString& noColorString)

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

void QgsColorButton::setShowMenu(bool showMenu)

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

Parameters
showMenu	set to false to hide the drop-down menu

The default behavior is to show the menu.

void QgsColorButton::setShowNoColor(const bool showNoColorOption)

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

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

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

void QgsColorButton::setShowNull(bool showNull)

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

bool QgsColorButton::showMenu() const

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

Returns	true if drop-down menu is shown

bool QgsColorButton::showNoColor() const

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

Returns	true if the no color option is shown.

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

bool QgsColorButton::showNull() const

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

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

Is emitted whenever a new color is set for the button.

Parameters
color	New color

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

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

void QgsColorButton::copyColor() public slot

Copies the current color to the clipboard.

void QgsColorButton::pasteColor() public 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.

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

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

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

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

void QgsColorButton::setColor(const QColor& color) public slot

Sets the current color for the button.

Parameters
color	new color for the button

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

void QgsColorButton::setToDefaultColor() public slot

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

void QgsColorButton::setToNoColor() public slot

Sets color to a totally transparent color.

void QgsColorButton::setToNull() public slot

Sets color to null.