QgsColorRampButton class

A cross platform button subclass for selecting color ramps.

Contents

Will open color ramp dialogs when clicked. Offers live updates to button from color ramp dialog. An attached drop-down menu allows for access to saved color ramps, as well as option to invert the current color ramp and create new ramps.

Constructors, destructors, conversion operators

QgsColorRampButton(QWidget* parent = nullptr, const QString& dialogTitle = QString())
Construct a new color ramp button.

Public functions

auto acceptLiveUpdates() const -> bool
Returns whether the button accepts live updates from QgsColorRampDialog.
auto colorRamp() const -> QgsColorRamp*
Returns a copy of the current color ramp.
auto colorRampDialogTitle() const -> QString
Returns the title for the color ramp dialog window.
auto colorRampName() const -> QString
Returns the name of the current color ramp when it's available in the style manager.
auto context() const -> QString
Returns the context string for the color ramp button.
auto defaultColorRamp() const -> QgsColorRamp*
Returns a copy of the default color ramp for the button, which is shown in the button's drop-down menu for the "default color ramp" option.
auto isNull() const -> bool
Returns true if the current color is null.
auto isRandomColorRamp() const -> bool
Returns true if the current color is null.
void setAcceptLiveUpdates(const bool accept)
Sets whether the button accepts live updates from QgsColorRampDialog.
void setColorRampDialogTitle(const QString& title)
Set the title for the color ramp dialog window.
void setColorRampName(const QString& name)
Sets the name of the current color ramp when it's available in the style manager.
void setContext(const QString& context)
Sets the context string for the color ramp button.
void setDefaultColorRamp(QgsColorRamp* colorramp)
Sets the default color ramp for the button, which is shown in the button's drop-down menu for the "default color ramp" option.
void setShowGradientOnly(bool gradientonly)
Sets whether the color ramp button only shows gradient type ramps.
void setShowMenu(bool showMenu)
Sets whether the drop-down menu should be shown for the button.
void setShowNull(bool showNull)
Sets whether a set to null (clear) option is shown in the button's drop-down menu.
void setShowRandomColorRamp(bool showRandom)
Sets whether a random colors option is shown in the button's drop-down menu.
auto showGradientOnly() const -> bool
Returns true if the color ramp button only shows gradient type ramps.
auto showMenu() const -> bool
Returns whether the drop-down menu is shown for the button.
auto showNull() const -> bool
Returns whether the set to null (clear) option is shown in the button's drop-down menu.
auto showRandomColorRamp() const -> bool
Returns whether random colors option is shown in the button's drop-down menu.

Signals

void colorRampChanged()
Emitted whenever a new color ramp is set for the button.

Public slots

void setButtonBackground(QgsColorRamp* colorramp = nullptr)
Sets the background pixmap for the button based upon current color ramp.
void setColorRamp(QgsColorRamp* colorramp)
Sets the current color ramp for the button.
void setColorRampFromName(const QString& name = QString())
Sets the current color ramp for the button using a saved color ramp name.
void setRandomColorRamp()
Sets the current color ramp for the button to random colors.
void setToDefaultColorRamp()
Sets color ramp to the button's default color ramp, if set.
void setToNull()
Sets color ramp to null.

Protected functions

void mousePressEvent(QMouseEvent* e) override
Reimplemented to detect right mouse button clicks on the color ramp button.

Function documentation

QgsColorRampButton::QgsColorRampButton(QWidget* parent = nullptr, const QString& dialogTitle = QString())

Construct a new color ramp button.

Use parent to attach a parent QWidget to the dialog. Use dialogTitle string to define the title to show in the color ramp dialog

bool QgsColorRampButton::acceptLiveUpdates() const

Returns whether the button accepts live updates from QgsColorRampDialog.

Returns true if the button will be accepted immediately when the dialog's color ramp changes

QgsColorRamp* QgsColorRampButton::colorRamp() const

Returns a copy of the current color ramp.

QString QgsColorRampButton::colorRampDialogTitle() const

Returns the title for the color ramp dialog window.

Returns title for the color ramp dialog

QString QgsColorRampButton::colorRampName() const

Returns the name of the current color ramp when it's available in the style manager.

QString QgsColorRampButton::context() const

Returns the context string for the color ramp button.

Returns context context string for the color dialog button's color ramp preview icons

The context string is passed to all color ramp preview icons shown in the button's drop-down menu, to (eventually) allow them to customize their display colors based on the context.

QgsColorRamp* QgsColorRampButton::defaultColorRamp() const

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

Returns default color ramp for the button. Returns a null pointer if the default color ramp option is disabled.

bool QgsColorRampButton::isNull() const

Returns true if the current color is null.

bool QgsColorRampButton::isRandomColorRamp() const

Returns true if the current color is null.

void QgsColorRampButton::setAcceptLiveUpdates(const bool accept)

Sets whether the button accepts live updates from QgsColorRampDialog.

Parameters
accept set to true to enable live updates

Live updates may cause changes that are not undoable on QColorRampDialog cancel.

void QgsColorRampButton::setColorRampDialogTitle(const QString& title)

Set the title for the color ramp dialog window.

Parameters
title Title for the color ramp dialog

void QgsColorRampButton::setColorRampName(const QString& name)

Sets the name of the current color ramp when it's available in the style manager.

Parameters
name Name of the saved color ramp

void QgsColorRampButton::setContext(const QString& context)

Sets the context string for the color ramp button.

Parameters
context context string for the color dialog button's color ramp preview icons

The context string is passed to all color ramp preview icons shown in the button's drop-down menu, to (eventually) allow them to customize their display colors based on the context.

void QgsColorRampButton::setDefaultColorRamp(QgsColorRamp* colorramp)

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

Parameters
colorramp default color ramp for the button. Set to a null pointer to disable the default color ramp option. The ramp will be cloned and ownership is not transferred.

void QgsColorRampButton::setShowGradientOnly(bool gradientonly)

Sets whether the color ramp button only shows gradient type ramps.

Parameters
gradientonly set to true to show only gradient type ramps

void QgsColorRampButton::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 QgsColorRampButton::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

void QgsColorRampButton::setShowRandomColorRamp(bool showRandom)

Sets whether a random colors option is shown in the button's drop-down menu.

Parameters
showRandom set to true to show a random colors option

bool QgsColorRampButton::showGradientOnly() const

Returns true if the color ramp button only shows gradient type ramps.

bool QgsColorRampButton::showMenu() const

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

Returns true if drop-down menu is shown

bool QgsColorRampButton::showNull() const

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

bool QgsColorRampButton::showRandomColorRamp() const

Returns whether random colors option is shown in the button's drop-down menu.

void QgsColorRampButton::colorRampChanged() signal

Emitted whenever a new color ramp is set for the button.

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

void QgsColorRampButton::setButtonBackground(QgsColorRamp* colorramp = nullptr) public slot

Sets the background pixmap for the button based upon current color ramp.

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

void QgsColorRampButton::setColorRamp(QgsColorRamp* colorramp) public slot

Sets the current color ramp for the button.

Parameters
colorramp New color ramp for the button. The ramp will be cloned and ownership is not transferred.

Will emit a colorRampChanged() signal if the color ramp is different to the previous color ramp.

void QgsColorRampButton::setColorRampFromName(const QString& name = QString()) public slot

Sets the current color ramp for the button using a saved color ramp name.

Parameters
name Name of saved color ramp

Will emit a colorRampChanged() signal if the color ramp is different to the previous color ramp.

void QgsColorRampButton::setRandomColorRamp() public slot

Sets the current color ramp for the button to random colors.

Will emit a colorRampChanged() signal if the color ramp is different to the previous color ramp.

void QgsColorRampButton::setToDefaultColorRamp() public slot

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

void QgsColorRampButton::setToNull() public slot

Sets color ramp to null.