QGIS API Documentation  2.6.0-Brighton
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Public Types | Public Slots | Signals | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Properties | List of all members
QgsColorButtonV2 Class Reference

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

#include <qgscolorbuttonv2.h>

Public Types

enum  Behaviour { ShowDialog = 0, SignalOnly }

Public Slots

void setColor (const QColor &color)
 Sets the current color for the button.
void setButtonBackground (const QColor color=QColor())
 Sets the background pixmap for the button based upon color and transparency.
void copyColor ()
 Copies the current color to the clipboard.
void pasteColor ()
 Pastes a color from the clipboard to the color button.
void activatePicker ()
 Activates the color picker tool, which allows for sampling a color from anywhere on the screen.
void setToNoColor ()
 Sets color to a totally transparent color.
void setToDefaultColor ()
 Sets color to the button's default color, if set.

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 behaviour is set to SignalOnly.

Public Member Functions

 QgsColorButtonV2 (QWidget *parent=0, QString cdt="", QgsColorSchemeRegistry *registry=0)
 Construct a new color button.
virtual ~QgsColorButtonV2 ()
virtual QSize sizeHint () const
QColor color () const
 Return the currently selected color.
void setAllowAlpha (const bool allowAlpha)
 Sets whether alpha modification (transparency) is permitted for the color.
bool allowAlpha () const
 Returns whether alpha modification (transparency) is permitted for the color.
void setColorDialogTitle (const QString title)
 Set the title for the color chooser dialog window.
QString colorDialogTitle () const
 Returns the title for the color chooser dialog window.
bool acceptLiveUpdates () const
 Returns whether the button accepts live updates from QColorDialog.
void setAcceptLiveUpdates (const bool accept)
 Sets whether the button accepts live updates from QColorDialog.
void setShowMenu (const bool showMenu)
 Sets whether the drop down menu should be shown for the button.
bool showMenu () const
 Returns whether the drop down menu is shown for the button.
void setBehaviour (const Behaviour behaviour)
 Sets the behaviour for when the button is clicked.
Behaviour behaviour () const
 Returns the behaviour for when the button is clicked.
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.
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.
void setShowNoColor (const bool showNoColorOption)
 Sets whether the "no color" option should be shown in the button's drop down menu.
bool showNoColor () const
 Returns whether the "no color" option is shown in the button's drop down menu.
void setNoColorString (const QString noColorString)
 Sets the string to use for the "no color" option in the button's drop down menu.
QString noColorString () const
 Returns the string used for the "no color" option in the button's drop down menu.
void setContext (const QString context)
 Sets the context string for the color button.
QString context () const
 Returns the context string for the color button.
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.
QgsColorSchemeRegistrycolorSchemeRegistry ()
 Returns the color scheme registry for the button, which controls the color swatch grids that are shown in the button's drop down menu.

Protected Member Functions

void changeEvent (QEvent *e)
void showEvent (QShowEvent *e)
void resizeEvent (QResizeEvent *event)
void mousePressEvent (QMouseEvent *e)
 Reimplemented to detect right mouse button clicks on the color button and allow dragging colors.
void mouseMoveEvent (QMouseEvent *e)
 Reimplemented to allow dragging colors from button.
void mouseReleaseEvent (QMouseEvent *e)
 Reimplemented to allow color picking.
void keyPressEvent (QKeyEvent *e)
 Reimplemented to allow cancelling color pick via keypress, and sample via space bar press.
void dragEnterEvent (QDragEnterEvent *e)
 Reimplemented to accept dragged colors.
void dragLeaveEvent (QDragLeaveEvent *e)
 Reimplemented to reset button appearance after drag leave.
void dropEvent (QDropEvent *e)
 Reimplemented to accept dropped colors.

Static Protected Member Functions

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

Properties

QString colorDialogTitle
bool acceptLiveUpdates
QColor color
bool allowAlpha
bool showMenu
Behaviour behaviour
QColor defaultColor
bool showNoColor
QString noColorString
QString context

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.

Note
Added in version 2.5

Member Enumeration Documentation

Specifies the behaviour when the button is clicked

Enumerator:
ShowDialog 

show a color picker dialog when clicked

SignalOnly 

emit colorClicked signal only, no dialog

Constructor & Destructor Documentation

QgsColorButtonV2::QgsColorButtonV2 ( QWidget *  parent = 0,
QString  cdt = "",
QgsColorSchemeRegistry registry = 0 
)

Construct a new color button.

Parameters
parentThe parent QWidget for the dialog
cdtThe title to show in the color chooser dialog
registrya 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
QgsColorButtonV2::~QgsColorButtonV2 ( )
virtual

Member Function Documentation

bool QgsColorButtonV2::acceptLiveUpdates ( ) const
inline

Returns whether the button accepts live updates from QColorDialog.

Returns
true if the button will be accepted immediately when the dialog's color changes
See Also
setAcceptLiveUpdates
void QgsColorButtonV2::activatePicker ( )
slot

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

bool QgsColorButtonV2::allowAlpha ( ) const
inline

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

Returns
true if alpha modification is allowed
See Also
setAllowAlpha
Behaviour QgsColorButtonV2::behaviour ( ) const
inline

Returns the behaviour for when the button is clicked.

Returns
behaviour when button is clicked
See Also
setBehaviour
void QgsColorButtonV2::changeEvent ( QEvent *  e)
protected
QColor QgsColorButtonV2::color ( ) const

Return the currently selected color.

Returns
currently selected color
See Also
setColor
void QgsColorButtonV2::colorChanged ( const QColor &  color)
signal

Is 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
void QgsColorButtonV2::colorClicked ( const QColor  color)
signal

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

Parameters
colorbutton color
See Also
setBehaviour
behaviour
QString QgsColorButtonV2::colorDialogTitle ( ) const

Returns the title for the color chooser dialog window.

Returns
title for the color chooser dialog
See Also
setColorDialogTitle
QgsColorSchemeRegistry* QgsColorButtonV2::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
QString QgsColorButtonV2::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 customise their display colors based on the context.

Returns
context string for the color button's color swatch grids
See Also
setContext
void QgsColorButtonV2::copyColor ( )
slot

Copies the current color to the clipboard.

See Also
pasteColor
QColor QgsColorButtonV2::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
void QgsColorButtonV2::dragEnterEvent ( QDragEnterEvent *  e)
protected

Reimplemented to accept dragged colors.

void QgsColorButtonV2::dragLeaveEvent ( QDragLeaveEvent *  e)
protected

Reimplemented to reset button appearance after drag leave.

void QgsColorButtonV2::dropEvent ( QDropEvent *  e)
protected

Reimplemented to accept dropped colors.

void QgsColorButtonV2::keyPressEvent ( QKeyEvent *  e)
protected

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

void QgsColorButtonV2::mouseMoveEvent ( QMouseEvent *  e)
protected

Reimplemented to allow dragging colors from button.

void QgsColorButtonV2::mousePressEvent ( QMouseEvent *  e)
protected

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

void QgsColorButtonV2::mouseReleaseEvent ( QMouseEvent *  e)
protected

Reimplemented to allow color picking.

QString QgsColorButtonV2::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 (see setColorDialogOptions)
void QgsColorButtonV2::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
void QgsColorButtonV2::resizeEvent ( QResizeEvent *  event)
protected
void QgsColorButtonV2::setAcceptLiveUpdates ( const bool  accept)
inline

Sets whether the button accepts live updates from QColorDialog.

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

Parameters
acceptset to true to enable live updates
See Also
acceptLiveUpdates
void QgsColorButtonV2::setAllowAlpha ( const bool  allowAlpha)

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

Defaults to false.

Parameters
allowAlphaset to true to allow alpha modification
See Also
allowAlpha
void QgsColorButtonV2::setBehaviour ( const Behaviour  behaviour)

Sets the behaviour for when the button is clicked.

The default behaviour is to show a color picker dialog.

Parameters
behaviourbehaviour when button is clicked
See Also
behaviour
void QgsColorButtonV2::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
void QgsColorButtonV2::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
void QgsColorButtonV2::setColorDialogTitle ( const QString  title)

Set the title for the color chooser dialog window.

Parameters
titleTitle for the color chooser dialog
See Also
colorDialogTitle
void QgsColorButtonV2::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
void QgsColorButtonV2::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 customise their display colors based on the context.

Parameters
contextcontext string for the color button's color swatch grids
See Also
context
void QgsColorButtonV2::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
void QgsColorButtonV2::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
Note
The "no color" option is only shown if the color button is set to show an alpha channel in the color dialog (see setColorDialogOptions)
void QgsColorButtonV2::setShowMenu ( const bool  showMenu)

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

The default behaviour is to show the menu.

Parameters
showMenuset to false to hide the drop down menu
See Also
showMenu
void QgsColorButtonV2::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 (see setColorDialogOptions)
void QgsColorButtonV2::setToDefaultColor ( )
slot

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

See Also
setDefaultColor
defaultColor
void QgsColorButtonV2::setToNoColor ( )
slot

Sets color to a totally transparent color.

Note
If the color button is not set to show an alpha channel in the color dialog (see setColorDialogOptions) then the color will not be changed.
void QgsColorButtonV2::showEvent ( QShowEvent *  e)
protected
bool QgsColorButtonV2::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
bool QgsColorButtonV2::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 (see setColorDialogOptions)
QSize QgsColorButtonV2::sizeHint ( ) const
virtual
const QPixmap & QgsColorButtonV2::transparentBackground ( )
staticprotected

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

Property Documentation

bool QgsColorButtonV2::acceptLiveUpdates
readwrite
bool QgsColorButtonV2::allowAlpha
readwrite
Behaviour QgsColorButtonV2::behaviour
readwrite
QColor QgsColorButtonV2::color
readwrite
QString QgsColorButtonV2::colorDialogTitle
readwrite
QString QgsColorButtonV2::context
readwrite
QColor QgsColorButtonV2::defaultColor
readwrite
QString QgsColorButtonV2::noColorString
readwrite
bool QgsColorButtonV2::showMenu
readwrite
bool QgsColorButtonV2::showNoColor
readwrite

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