CMFCColorButton Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMFCColorButton Class.

The CMFCColorButton and CMFCColorBar Class classes are used together to implement a color picker control.

class CMFCColorButton : public CMFCButton  

Public Constructors

NameDescription
CMFCColorButton::CMFCColorButtonConstructs a new CMFCColorButton object.

Public Methods

NameDescription
CMFCColorButton::EnableAutomaticButtonEnables and disables an "automatic" button that is positioned above the regular color buttons. (The standard system automatic button is labeled Automatic.)
CMFCColorButton::EnableOtherButtonEnables and disables an "other" button that is positioned below the regular color buttons. (The standard system "other" button is labeled More Colors….)
CMFCColorButton::GetAutomaticColorRetrieves the current automatic color.
CMFCColorButton::GetColorRetrieves a button's color.
CMFCColorButton::SetColorSets a button's color.
CMFCColorButton::SetColorNameSets a color name.
CMFCColorButton::SetColumnsNumberSets the number of columns on the color picker dialog box.
CMFCColorButton::SetDocumentColorsSpecifies a list of document-specific colors that are displayed on the color picker dialog box.
CMFCColorButton::SetPaletteSpecifies a palette of standard display colors.
CMFCColorButton::SizeToContentChanges the size of the button control, depending on its text and image size.

Protected Methods

NameDescription
CMFCColorButton::IsDrawXPThemeIndicates whether the current color button is displayed in the visual style of Windows XP.
CMFCColorButton::OnDrawCalled by the framework to display an image of the button.
CMFCColorButton::OnDrawBorderCalled by the framework to display the button's border.
CMFCColorButton::OnDrawFocusRectCalled by the framework to display a focus rectangle when the button has a focus.
CMFCColorButton::OnShowColorPopupCalled by the framework when the color picker dialog box is about to be displayed.
CMFCColorButton::RebuildPaletteInitializes the m_pPalette protected data member to the specified palette or the default system palette.
CMFCColorButton::UpdateColorCalled by the framework when the user selects a color from the palette of the color picker dialog box.

Data Members

NameDescription
m_bAltColorDlgA Boolean. If TRUE, the framework displays the CMFCColorDialog color dialog box when the other button is clicked, or if FALSE, the system color dialog box. The default value is TRUE. For more information, see CMFCColorButton::EnableOtherButton.
m_bAutoSetFocusA Boolean. If TRUE, the framework sets the focus on the color menu when the menu is displayed, or if FALSE, does not change the focus. The default value is TRUE.
CMFCColorButton::m_bEnabledInCustomizeModeIndicates whether customization mode is enabled for the color button.
m_ColorA COLORREF value. Contains the currently selected color.
m_ColorAutomaticA COLORREF value. Contains the currently selected default color.
m_ColorsA CArray of COLORREF values. Contains the currently available colors.
m_lstDocColorsA CList of COLORREF values. Contains the current document colors.
m_nColumnsAn integer. Contains the number of columns to display in the grid of colors in a color selection menu.
m_pPaletteA pointer to a CPalette. Contains the colors that are available in the current color selection menu.
m_pPopupA pointer to a CMFCColorPopupMenu Class object. The color selection menu that is displayed when you click the color button.
m_strAutoColorTextA string. The label of the "automatic" button in a color selection menu.
m_strDocColorsTextA string. The label of the button in a color selection menu that displays the document colors.
m_strOtherTextA string. The label of the "other" button in a color selection menu.

By default, the CMFCColorButton class behaves as a push button that opens a color picker dialog box. The color picker dialog box contains an array of small color buttons and an "other" button that displays a custom color picker. (The standard system "other" button is labeled More Colors….) When a user selects a new color, the CMFCColorButton object reflects the change and displays the selected color.

Create a color button control either directly in your code, or by using the ClassWizard tool and a dialog box template. If you create a color button control directly, add a CMFCColorButton variable to your application, and then call the constructor and Create methods of the CMFCColorButton object. If you use the ClassWizard, add a CButton variable to your application, and then change the type of the variable from CButton to CMFCColorButton.

The color picker dialog box ( CMFCColorBar Class) is displayed by the CMFCColorButton::OnShowColorPopup method when the framework calls the OnLButtonDown event handler. The CMFCColorButton::OnShowColorPopup method can be overridden to support custom color selection.

The CMFCColorButton object notifies its parent that a color is changing by sending it a WM_COMMAND | BN_CLICKED notification. The parent uses the CMFCColorButton::GetColor method to retrieve the current color.

The following example demonstrates how to configure a color button by using various methods in the CMFCColorButton class. The methods set the color of the color button and its number of columns, and enable the automatic and the other buttons. This example is part of the Status Bar Demo sample.

	CMFCColorButton	m_wndTextColor;

	m_wndTextColor.EnableAutomaticButton (_T("Default"), afxGlobalData.clrBtnText);
	m_wndTextColor.EnableOtherButton (_T("Other..."));
	m_wndTextColor.SetColor ((COLORREF)-1);
	m_wndTextColor.SetColorName((COLORREF)-1, "Default Color");
	m_wndTextColor.SetColumnsNumber(3);

Header: afxcolorbutton.h

Constructs a new CMFCColorButton object.

CMFCColorButton();

Enable or disable the "automatic" button of a color picker control and set the automatic (default) color.

void EnableAutomaticButton(
    LPCTSTR lpszLabel,  
    COLORREF colorAutomatic,  
    BOOL bEnable=TRUE);

Parameters

[in] lpszLabel
Specifies the automatic button's text.

[in] colorAutomatic
An RGB value that specifies the automatic button's default color.

[in] bEnable
Specifies whether the automatic button is enabled or disabled.

Remarks

Enable or disable the "other" button, which appears below regular color buttons.

void EnableOtherButton(
    LPCTSTR lpszLabel,  
    BOOL bAltColorDlg=TRUE,  
    BOOL bEnable=TRUE);

Parameters

[in] lpszLabel
Specifies the button's text.

[in] bAltColorDlg
Specifies whether the CMFCColorDialog dialog box or the system color dialog box is opened when the user clicks the button.

[in] bEnable
Specifies whether the "other" button is enabled or disabled.

Remarks

Click the "other" button to display a color dialog box. If the bAltColorDlg parameter is TRUE, the CMFCColorDialog Class is displayed; otherwise, the system color dialog box is displayed.

Retrieves the current automatic (default) color.

COLORREF GetAutomaticColor() const;  

Return Value

An RGB value representing the current automatic color.

Remarks

The current automatic color is set by the CMFCColorButton::EnableAutomaticButton method.

Retrieves the currently selected color.

COLORREF GetColor() const;  

Return Value

An RGB value.

Remarks

Indicates whether the current color button is displayed in the visual style of Windows XP.

BOOL IsDrawXPTheme() const;  

Return Value

TRUE if visual styles are supported and the current color button is displayed in the visual style of Windows XP; otherwise, FALSE.

Sets a color button to customization mode.

BOOL m_bEnabledInCustomizeMode;  

Remarks

If you need to add a color button to a customization dialog's page (or allow the user to make another color selection during customization), enable the button by setting the m_bEnabledInCustomizeMode member to TRUE. By default, this member is set to FALSE.

Called by the framework to render an image of the button.

virtual void OnDraw(
    CDC* pDC,  
    const CRect& rect,  
    UINT uiState);

Parameters

[in] pDC
Points to the device context that is used to render the image of the button.

[in] rect
A rectangle that bounds the button.

[in] uiState
Specifies the visual state of the button.

Remarks

Override this method to customize the rendering process.

Called by the framework to display the border of the button.

virtual void OnDrawBorder(
    CDC* pDC,  
    CRect& rectClient,  
    UINT uiState);

Parameters

[in] pDC
Points to the device context used to draw the border.

[in] rectClient
A rectangle in the device context that is specified by the the pDC parameter that defines the boundaries of the button to be drawn.

[in] uiState
Specifies the visual state of the button.

Remarks

Override this function to customize the color button's border appearance.

Called by the framework to display a focus rectangle when the button has focus.

virtual void OnDrawFocusRect(
    CDC* pDC,  
    const CRect& rectClient);

Parameters

[in] pDC
Points to the device context used to draw the focus rectangle.

[in] rectClient
A rectangle in the device context specified by the pDC parameter that defines the boundaries of the button.

Remarks

Override this method to customize appearance of the focus rectangle.

Called before the popup color bar is displayed.

virtual void OnShowColorPopup();

Remarks

Initializes the m_pPalette protected data member to the specified palette or the default system palette.

void RebuildPalette(CPalette* pPal);

Parameters

ParameterDescription
[in] pPalA pointer to a logical palette or NULL. If NULL, the default system palette is used.

Specifies the color of the button.

void SetColor(COLORREF color);

Parameters

[in] color
An RGB value.

Remarks

Specifies the name of a color.

static void SetColorName(
    COLORREF color,  
    const CString& strName);

Parameters

[in] color
The color's RGB value.

[in] strName
The color's name.

Remarks

The list of color names is global per application. Consequently, this method transfers its parameters to CMFCColorBar::SetColorName.

Defines the number of columns that are displayed in the table of colors that is presented to the user during the user's color selection process.

void SetColumnsNumber(int nColumns);

Parameters

[in] nColumns
Specifies the number of columns.

Remarks

The user can select a color from a popup color bar that displays a table of predefined colors. Use this method to define the number of columns in the table.

Specifies a set of colors and the set's name. The set of colors is displayed using a CMFCColorBar Class object.

void SetDocumentColors(
    LPCTSTR lpszLabel,  
    CList<COLORREF,COLORREF>& lstColors);

Parameters

[in] lpszLabel
Specifies the label to be displayed with the set of document colors.

[in] lstColors
A reference to a list of RGB values.

Remarks

A CMFCColorButton object maintains a list of RGB values that are transferred to a CMFCColorBar Class object. When the color bar is displayed, these colors are shown in a special section whose label is specified by the lpszLabel parameter.

Specifies the standard colors to display on the popup color bar.

void SetPalette(CPalette* pPalette);

Parameters

[in] pPalette
A pointer to a color palette.

Remarks

Resizes the button control to fit its text and image.

virtual CSize SizeToContent(BOOL bCalcOnly=FALSE);

Parameters

[in] bCalcOnly
If nonzero, the new size of the button control is calculated but the actual size is not changed.

Return Value

A CSize object that specifies a new button control size.

Remarks

Called by the framework when the user selects a color from the color bar that displays when the user clicks the color button.

virtual void UpdateColor(COLORREF color);

Parameters

[in] color
A color selected by the user.

Remarks

The UpdateColor function changes the currently selected button's color and notifies its parent by sending a WM_COMMAND message with a BN_CLICKED standard notification. Use the CMFCColorButton::GetColor method to retrieve the selected color.

Hierarchy Chart
Classes
CMFCButton Class
CMFCColorBar Class
CMFCColorButton::OnShowColorPopup
COLORREF
CPalette Class
CArray Class
CList Class
CString

Show: