QGIS API Documentation 4.3.0-Master (91d4a333d5d)
Loading...
Searching...
No Matches
QgsColorButton Class Reference

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 setToOpaqueColor ()
 Sets the color to a totally opaque one, leaving the other color components untouched.
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.
QString opaqueColorString () const
 Returns the string used for the "opaque 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 setOpaqueColorString (const QString &opaqueColorString)
 Sets the string to use for the "opaque 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 contextMenuEvent (QContextMenuEvent *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 mouseMoveEvent (QMouseEvent *e) override
 Reimplemented to allow dragging colors from button.
void mousePressEvent (QMouseEvent *e) override
 Reimplemented to allow dragging colors.
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
QString opaqueColorString
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 39 of file qgscolorbutton.h.

Member Enumeration Documentation

◆ 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 67 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 53 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 757 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 107 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 151 of file qgscolorbutton.h.

◆ changeEvent()

void QgsColorButton::changeEvent ( QEvent * e)
overrideprotected

Definition at line 582 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 762 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
colorNew 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
colorbutton 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 780 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 296 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 278 of file qgscolorbutton.h.

◆ contextMenuEvent()

void QgsColorButton::contextMenuEvent ( QContextMenuEvent * e)
overrideprotected

Definition at line 223 of file qgscolorbutton.cpp.

◆ copyColor

void QgsColorButton::copyColor ( )
slot

Copies the current color to the clipboard.

See also
pasteColor

Definition at line 737 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 410 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 169 of file qgscolorbutton.h.

◆ dragEnterEvent()

void QgsColorButton::dragEnterEvent ( QDragEnterEvent * e)
overrideprotected

Reimplemented to accept dragged colors.

Definition at line 333 of file qgscolorbutton.cpp.

◆ dragLeaveEvent()

void QgsColorButton::dragLeaveEvent ( QDragLeaveEvent * e)
overrideprotected

Reimplemented to reset button appearance after drag leave.

Definition at line 351 of file qgscolorbutton.cpp.

◆ dropEvent()

void QgsColorButton::dropEvent ( QDropEvent * e)
overrideprotected

Reimplemented to accept dropped colors.

Definition at line 358 of file qgscolorbutton.cpp.

◆ event()

bool QgsColorButton::event ( QEvent * e)
overrideprotected

Definition at line 182 of file qgscolorbutton.cpp.

◆ isNull()

bool QgsColorButton::isNull ( ) const

Returns true if the current color is null.

See also
setShowNull()
showNull()

Definition at line 816 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 320 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 821 of file qgscolorbutton.cpp.

◆ minimumSizeHint()

QSize QgsColorButton::minimumSizeHint ( ) const
override

Definition at line 89 of file qgscolorbutton.cpp.

◆ mouseMoveEvent()

void QgsColorButton::mouseMoveEvent ( QMouseEvent * e)
overrideprotected

Reimplemented to allow dragging colors from button.

Definition at line 257 of file qgscolorbutton.cpp.

◆ mousePressEvent()

void QgsColorButton::mousePressEvent ( QMouseEvent * e)
overrideprotected

Reimplemented to allow dragging colors.

Definition at line 214 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 251 of file qgscolorbutton.h.

◆ opaqueColorString()

QString QgsColorButton::opaqueColorString ( ) const
inline

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

Returns
string used for the "opaque color" menu option
See also
setOpaqueColorString
noColorString
Since
QGIS 4.4

Definition at line 260 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 746 of file qgscolorbutton.cpp.

◆ resizeEvent()

void QgsColorButton::resizeEvent ( QResizeEvent * event)
overrideprotected

Definition at line 609 of file qgscolorbutton.cpp.

◆ setAllowOpacity()

void QgsColorButton::setAllowOpacity ( bool allowOpacity)

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

Defaults to false.

Parameters
allowOpacityset to true to allow opacity modification
See also
allowOpacity()

Definition at line 770 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
behaviorbehavior when button is clicked
See also
behavior

Definition at line 795 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
colorColor for button background. If no color is specified, the button's current color will be used

Definition at line 641 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
colornew color for the button
See also
color

Definition at line 617 of file qgscolorbutton.cpp.

◆ setColorDialogTitle()

void QgsColorButton::setColorDialogTitle ( const QString & title)

Set the title for the color chooser dialog window.

Parameters
titleTitle for the color chooser dialog
See also
colorDialogTitle

Definition at line 775 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
registrycolor 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 287 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
contextcontext string for the color button's color swatch grids
See also
context

Definition at line 269 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
colordefault color for the button. Set to an invalid QColor to disable the default color option.
See also
defaultColor

Definition at line 800 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
noColorStringstring to use for the "no color" menu option
See also
noColorString
setShowNoColor
setOpaqueColorString
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 202 of file qgscolorbutton.h.

◆ setOpaqueColorString()

void QgsColorButton::setOpaqueColorString ( const QString & opaqueColorString)
inline

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

This option is shown whenever the button's current color is not totally opaque, so that the transparency can be dropped again. It sits alongside the "no color" option which is hidden when the color is already totally transparent.

Parameters
opaqueColorStringstring to use for the "opaque color" menu option
See also
opaqueColorString
setNoColorString
Note
The "opaque color" option is only shown if the color button allows opacity, or if it is set to show the "no color" option
Since
QGIS 4.4

Definition at line 218 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
showMenuset to false to hide the drop-down menu
See also
showMenu

Definition at line 785 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
showNoColorOptionset 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, and is hidden when the color is already totally transparent

Definition at line 180 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
showNullset to true to show a null option
nullStringtranslated 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 805 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 160 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
setToOpaqueColor()
setToNull()

Definition at line 200 of file qgscolorbutton.cpp.

◆ setToNull

void QgsColorButton::setToNull ( )
slot

Sets color to null.

See also
setToDefaultColor()
setToNoColor()
cleared()

Definition at line 170 of file qgscolorbutton.cpp.

◆ setToOpaqueColor

void QgsColorButton::setToOpaqueColor ( )
slot

Sets the color to a totally opaque one, leaving the other color components untouched.

See also
setToNoColor()
setToNull()
Since
QGIS 4.4

Definition at line 207 of file qgscolorbutton.cpp.

◆ showEvent()

void QgsColorButton::showEvent ( QShowEvent * e)
overrideprotected

Definition at line 603 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 136 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 191 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 811 of file qgscolorbutton.cpp.

◆ sizeHint()

QSize QgsColorButton::sizeHint ( ) const
override

Definition at line 94 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 99 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 176 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 375 of file qgscolorbutton.cpp.

◆ QgsColorTooltip

friend class QgsColorTooltip
friend

Definition at line 563 of file qgscolorbutton.h.

Property Documentation

◆ allowOpacity

bool QgsColorButton::allowOpacity
readwrite

Definition at line 54 of file qgscolorbutton.h.

◆ behavior

Behavior QgsColorButton::behavior
readwrite

Definition at line 56 of file qgscolorbutton.h.

◆ color

QColor QgsColorButton::color
readwrite

Definition at line 53 of file qgscolorbutton.h.

◆ colorDialogTitle

QString QgsColorButton::colorDialogTitle
readwrite

Definition at line 52 of file qgscolorbutton.h.

◆ context

QString QgsColorButton::context
readwrite

Definition at line 61 of file qgscolorbutton.h.

◆ defaultColor

QColor QgsColorButton::defaultColor
readwrite

Definition at line 57 of file qgscolorbutton.h.

◆ noColorString

QString QgsColorButton::noColorString
readwrite

Definition at line 59 of file qgscolorbutton.h.

◆ opaqueColorString

QString QgsColorButton::opaqueColorString
readwrite

Definition at line 60 of file qgscolorbutton.h.

◆ showMenu

bool QgsColorButton::showMenu
readwrite

Definition at line 55 of file qgscolorbutton.h.

◆ showNoColor

bool QgsColorButton::showNoColor
readwrite

Definition at line 58 of file qgscolorbutton.h.


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