Class: QgsColorButton

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.

QgsColorButton in a default state

Class Hierarchy

Base classes

QToolButton
QAbstractButton
QWidget
QObject
QPaintDevice

Methods

activatePicker	Activates the color picker tool, which allows for sampling a color from anywhere on the screen
allowOpacity	Returns whether opacity modification (transparency) is permitted for the color.
behavior	Returns the behavior for when the button is clicked.
color	Returns the currently selected color.
colorDialogTitle	Returns the title for the color chooser dialog window.
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.
context	Returns the context string for the color button.
copyColor	Copies the current color to the clipboard
defaultColor	Returns the default color for the button, which is shown in the button's drop-down menu for the "default color" option.
dragEnterEvent	Reimplemented to accept dragged colors
dragLeaveEvent	Reimplemented to reset button appearance after drag leave
dropEvent	Reimplemented to accept dropped colors
isNull	Returns True if the current color is null.
keyPressEvent	Reimplemented to allow canceling color pick via keypress, and sample via space bar press
linkToProjectColor	Sets the button to link to an existing project color, by color name.
linkedProjectColorName	Returns the linked project color name, if set.
mouseMoveEvent	Reimplemented to allow dragging colors from button
mousePressEvent	Reimplemented to detect right mouse button clicks on the color button and allow dragging colors
mouseReleaseEvent	Reimplemented to allow color picking
noColorString	Returns the string used for the "no color" option in the button's drop-down menu.
pasteColor	Pastes a color from the clipboard to the color button.
setAllowOpacity	Sets whether opacity modification (transparency) is permitted for the color.
setBehavior	Sets the behavior for when the button is clicked.
setButtonBackground	Sets the background pixmap for the button based upon color and transparency.
setColor	Sets the current color for the button.
setColorDialogTitle	Set the title for the color chooser dialog window.
setColorSchemeRegistry	Sets the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop-down menu.
setContext	Sets the context string for the color button.
setDefaultColor	Sets the default color for the button, which is shown in the button's drop-down menu for the "default color" option.
setNoColorString	Sets the string to use for the "no color" option in the button's drop-down menu.
setShowMenu	Sets whether the drop-down menu should be shown for the button.
setShowNoColor	Sets whether the "no color" option should be shown in the button's drop-down menu.
setShowNull	Sets whether a set to null (clear) option is shown in the button's drop-down menu.
setToDefaultColor	Sets color to the button's default color, if set.
setToNoColor	Sets color to a totally transparent color.
setToNull	Sets color to null.
showMenu	Returns whether the drop-down menu is shown for the button.
showNoColor	Returns whether the "no color" option is shown in the button's drop-down menu.
showNull	Returns whether the set to null (clear) option is shown in the button's drop-down menu.
transparentBackground	Returns a checkboard pattern pixmap for use as a background to transparent colors
unlink	Unlinks the button from a project color.

Static Methods

createMenuIcon

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

Signals

cleared	Emitted when the color is cleared (set to null).
colorChanged	Emitted whenever a new color is set for the button.
colorClicked	Emitted when the button is clicked, if the button's behavior is set to SignalOnly
unlinked	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.

Attributes

ShowDialog
SignalOnly

class qgis.gui.QgsColorButton

Bases: QToolButton

__init__(parent: QWidget | None = None, cdt: str | None = '', registry: QgsColorSchemeRegistry | None = None)

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

Parameters:

• parent (Optional[QWidget] = None)

• cdt (Optional[str] = '')

• registry (Optional[QgsColorSchemeRegistry] = None)

class Behavior

Bases: int

ShowDialog = 0

SignalOnly = 1

activatePicker(self)

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

allowOpacity(self) → bool

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

Return type:

bool

Returns:

True if opacity modification is allowed

See also

setAllowOpacity()

behavior(self) → QgsColorButton.Behavior

Returns the behavior for when the button is clicked.

Return type:

QgsColorButton.Behavior

Returns:

behavior when button is clicked

See also

setBehavior()

signal cleared

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

See also

setToNull()

Added in version 3.12.

color(self) → QColor

Returns the currently selected color.

Return type:

QColor

Returns:

currently selected color

See also

setColor()

signal colorChanged(color: QColor)

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 (QColor) – New color

signal colorClicked(color: QColor)

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

Parameters:

color (QColor) – button color

See also

setBehavior()

See also

behavior()

colorDialogTitle(self) → str

Returns the title for the color chooser dialog window.

Return type:

str

Returns:

title for the color chooser dialog

See also

setColorDialogTitle()

colorSchemeRegistry(self) → QgsColorSchemeRegistry | None

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

Return type:

Optional[QgsColorSchemeRegistry]

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

context(self) → str

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.

Return type:

str

Returns:

context string for the color button’s color swatch grids

See also

setContext()

copyColor(self)

Copies the current color to the clipboard

See also

pasteColor()

static createMenuIcon(color: QColor | Qt.GlobalColor, showChecks: bool = True) → QPixmap

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.

Added in version 3.6.

Parameters:

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

• showChecks (bool = True)

Return type:

QPixmap

defaultColor(self) → QColor

Returns the default color for the button, which is shown in the button’s drop-down menu for the “default color” option.

Return type:

QColor

Returns:

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

See also

setDefaultColor()

dragEnterEvent(self, e: QDragEnterEvent | None)

Reimplemented to accept dragged colors

Parameters:

e (Optional[QDragEnterEvent])

dragLeaveEvent(self, e: QDragLeaveEvent | None)

Reimplemented to reset button appearance after drag leave

Parameters:

e (Optional[QDragLeaveEvent])

dropEvent(self, e: QDropEvent | None)

Reimplemented to accept dropped colors

Parameters:

e (Optional[QDropEvent])

isNull(self) → bool

Returns True if the current color is null.

See also

setShowNull()

See also

showNull()

Return type:

bool

keyPressEvent(self, e: QKeyEvent | None)

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

Parameters:

e (Optional[QKeyEvent])

linkToProjectColor(self, name: str | None)

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

See also

unlink()

Added in version 3.6.

Parameters:

name (Optional[str])

linkedProjectColorName(self) → str

Returns the linked project color name, if set.

See also

linkToProjectColor()

Added in version 3.6.

Return type:

str

mouseMoveEvent(self, e: QMouseEvent | None)

Reimplemented to allow dragging colors from button

Parameters:

e (Optional[QMouseEvent])

mousePressEvent(self, e: QMouseEvent | None)

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

Parameters:

e (Optional[QMouseEvent])

mouseReleaseEvent(self, e: QMouseEvent | None)

Reimplemented to allow color picking

Parameters:

e (Optional[QMouseEvent])

noColorString(self) → str

Returns the string used for the “no color” option in the button’s drop-down menu.

Return type:

str

Returns:

string used for the “no color” menu option

See also

setNoColorString()

See also

showNoColor()

Note

The “no color” option is only shown if the color button is set to show an alpha channel in the color dialog

pasteColor(self)

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

setAllowOpacity(self, allowOpacity: bool)

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

Parameters:

allowOpacity (bool) – set to True to allow opacity modification

See also

allowOpacity()

setBehavior(self, behavior: QgsColorButton.Behavior)

Sets the behavior for when the button is clicked. The default behavior is to show a color picker dialog.

Parameters:

behavior (QgsColorButton.Behavior) – behavior when button is clicked

See also

behavior()

setButtonBackground(self, color: QColor | Qt.GlobalColor = QColor())

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 (Union[QColor, Qt.GlobalColor] = QColor()) – Color for button background. If no color is specified, the button’s current color will be used

setColor(self, color: QColor | Qt.GlobalColor)

Sets the current color for the button. Will emit a colorChanged signal if the color is different to the previous color.

Parameters:

color (Union[QColor, Qt.GlobalColor]) – new color for the button

See also

color()

setColorDialogTitle(self, title: str | None)

Set the title for the color chooser dialog window.

Parameters:

title (Optional[str]) – Title for the color chooser dialog

See also

colorDialogTitle()

setColorSchemeRegistry(self, registry: QgsColorSchemeRegistry | None)

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 (Optional[QgsColorSchemeRegistry]) – 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()

setContext(self, context: str | None)

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 (Optional[str]) – context string for the color button’s color swatch grids

See also

context()

setDefaultColor(self, color: QColor | Qt.GlobalColor)

Sets the default color for the button, which is shown in the button’s drop-down menu for the “default color” option.

Parameters:

color (Union[QColor, Qt.GlobalColor]) – default color for the button. Set to an invalid QColor to disable the default color option.

See also

defaultColor()

setNoColorString(self, noColorString: str | None)

Sets the string to use for the “no color” option in the button’s drop-down menu.

Parameters:

noColorString (Optional[str]) – string to use for the “no color” menu option

See also

noColorString()

See also

setShowNoColor()

Note

The “no color” option is only shown if the color button is set to show an alpha channel in the color dialog

setShowMenu(self, showMenu: bool)

Sets whether the drop-down menu should be shown for the button. The default behavior is to show the menu.

Parameters:

showMenu (bool) – set to False to hide the drop-down menu

See also

showMenu()

setShowNoColor(self, showNoColorOption: bool)

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 (bool) – set to True to show the no color option. This is disabled by default.

See also

showNoColor()

See also

setNoColorString()

Note

The “no color” option is only shown if the color button is set to show an alpha channel in the color dialog

setShowNull(self, showNull: bool, nullString: str | None = '')

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

Parameters:

• showNull (bool) – set to True to show a null option

• nullString (Optional[str] = '') – translated string to use for the null option. If not set, a default “Clear Color” string will be used.

See also

showNull()

See also

isNull()

setToDefaultColor(self)

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

See also

setDefaultColor()

See also

defaultColor()

See also

setToNull()

setToNoColor(self)

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

setToNull(self)

Sets color to null.

See also

setToDefaultColor()

See also

setToNoColor()

See also

cleared()

showMenu(self) → bool

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

Return type:

bool

Returns:

True if drop-down menu is shown

See also

setShowMenu()

showNoColor(self) → bool

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.

Return type:

bool

Returns:

True if the no color option is shown.

See also

setShowNoColor()

See also

noColorString()

Note

The “no color” option is only shown if the color button is set to show an alpha channel in the color dialog

showNull(self) → bool

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

See also

setShowNull()

See also

isNull()

Return type:

bool

transparentBackground() → QPixmap

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

Return type:

QPixmap

unlink(self)

Unlinks the button from a project color.

See also

unlinked()

See also

linkToProjectColor()

Added in version 3.6.

signal unlinked

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

See also

linkToProjectColor()

Added in version 3.6.