CMFCRibbonColorButton 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 CMFCRibbonColorButton Class.

The CMFCRibbonColorButton class implements a color button that you can add to a ribbon bar. The ribbon color button displays a drop-down menu that contains one or more color palettes.

Syntax

class CMFCRibbonColorButton : public CMFCRibbonGallery  

Members

Public Constructors

Public Methods

Remarks

The ribbon color button displays a color bar when a user presses it. By default, this color bar contains a color selection palette called the regular color area. Optionally, the color bar can display an Automatic button, which allows the user to select a default color, and an Other button, which displays a popup color palette that contains additional colors.

Example

The following example demonstrates how to use various methods in the CMFCRibbonColorButton class. The example shows how to construct a CMFCRibbonColorButton object, set the large image, enable the Automatic button, enable the Other button, set the number of columns, set the size of all the color elements that appear on the color bar, add a group of colors to the regular color area, and specify a list of RGB values to display in the document color area. This code snippet is part of the Draw Client sample.

 // Create the "Paper Color" button
    CMFCRibbonColorButton* pBtnPaperColor = new CMFCRibbonColorButton(ID_VIEW_PAPERCOLOR, _T("Paper Color\ng"), TRUE, 13, 1);
    pBtnPaperColor->SetAlwaysLargeImage();
    pBtnPaperColor->EnableAutomaticButton(_T("&Automatic"), RGB(255, 255, 255));
    pBtnPaperColor->EnableOtherButton(_T("&More Colors..."), _T("More Colors"));
    pBtnPaperColor->SetColumns(10);
    pBtnPaperColor->SetColorBoxSize(CSize(17, 17));
    // CList<COLORREF,COLORREF> m_lstMainColors
    pBtnPaperColor->AddColorsGroup(_T("Theme Colors"), m_lstMainColors, TRUE);
    // CList<COLORREF,COLORREF> m_lstAdditionalColors
    pBtnPaperColor->AddColorsGroup(_T(""), m_lstAdditionalColors, FALSE);
    // CList<COLORREF,COLORREF> m_lstStandardColors
    pBtnPaperColor->AddColorsGroup(_T("Standard Colors"), m_lstStandardColors, TRUE);
    CList<COLORREF,COLORREF> lstColors;
    lstColors.AddTail(RGB(255,0,0));
    lstColors.AddTail(RGB(0,255,0));
    lstColors.AddTail(RGB(0,0,255));
    pBtnPaperColor->SetDocumentColors( _T("Document Colors"), lstColors );

Inheritance Hierarchy

CObject

CMFCRibbonBaseElement

CMFCRibbonButton

CMFCRibbonGallery

CMFCRibbonColorButton

Requirements

Header: afxribboncolorbutton.h

CMFCRibbonColorButton::AddColorsGroup

Adds a group of colors to the regular color area.

void AddColorsGroup(
    LPCTSTR lpszName,  
    const CList<COLORREF,COLORREF>& lstColors,  
    BOOL bContiguousColumns=FALSE);

Parameters

[in] lpszName
The group name.

[in] lstColors
The list of colors.

[in] bContiguousColumns
Controls how the color items are displayed in the group. If TRUE, the color items are drawn without a vertical spacing. If FALSE, the color items are drawn with a vertical spacing.

Remarks

Use this function to make the color pop-up display several groups of colors. You can control how the colors are displayed in group.

CMFCRibbonColorButton::CMFCRibbonColorButton

Constructs a CMFCRibbonColorButton object.

CMFCRibbonColorButton();

 
CMFCRibbonColorButton(
    UINT nID,  
    LPCTSTR lpszText,  
    int nSmallImageIndex,  
    COLORREF color = RGB(0, 0, 0));

 
CMFCRibbonColorButton(
    UINT nID,  
    LPCTSTR lpszText,  
    BOOL bSimpleButtonLook,  
    int nSmallImageIndex,  
    int nLargeImageIndex,  
    COLORREF color = RGB(0, 0, 0));

Parameters

[in] nID
Specifies the command ID of the command to execute when a user clicks the button.

[in] lpszText
Specifies the text to appear on the button.

[in] nSmallImageIndex
The zero-based index of the small image to appear on the button.

[in] color
The color of the button (defaults to black).

[in] bSimpleButtonLook
If TRUE, the button is drawn as a simple rectangle.

[in] nLargeImageIndex
The zero-based index of the large image to appear on the button.

Return Value

Remarks

CMFCRibbonColorButton::EnableAutomaticButton

Specifies whether the Automatic button is enabled.

void EnableAutomaticButton(
    LPCTSTR lpszLabel,  
    COLORREF colorAutomatic,  
    BOOL bEnable=TRUE,  
    LPCTSTR lpszToolTip=NULL,  
    BOOL bOnTop=TRUE,  
    BOOL bDrawBorder=FALSE);

Parameters

[in] lpszLabel
The label for the Automatic button.

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

[in] bEnable
TRUE if the Automatic button is enabled; FALSE if it is disabled.

[in] lpszToolTip
The tooltip of the Automatic button.

[in] bOnTop
Specifies whether the Automatic button is at the top, before color palette.

[in] bDrawBorder
TRUE if the application draws a border around the color bar on the ribbon color button. Color bar displays the currently selected color. FALSE if the application does not draw a border

CMFCRibbonColorButton::EnableOtherButton

Enables the Other button.

void EnableOtherButton(
    LPCTSTR lpszLabel,  
    LPCTSTR lpszToolTip=NULL);

Parameters

lpszLabel
The button's label.

lpszToolTip
The tooltip text for the Other button.

Remarks

The Other button is the button that is displayed below the group of colors. When the user clicks the Other button, it displays a color dialog.

CMFCRibbonColorButton::GetAutomaticColor

Retrieves the current automatic-button color.

COLORREF GetAutomaticColor() const;  

Return Value

An RGB color value that represents the current automatic-button color.

Remarks

The automatic-button color is set by the colorAutomatic parameter passed to the CMFCRibbonColorButton::EnableAutomaticButton method.

CMFCRibbonColorButton::GetColor

Returns the currently selected color.

COLORREF GetColor() const;  

Return Value

The color selected by clicking the button.

CMFCRibbonColorButton::GetColorBoxSize

Returns the size of the color elements that appear on the color bar.

CSize GetColorBoxSize() const;  

Return Value

The size of the color buttons in the drop-down color palette.

CMFCRibbonColorButton::GetColumns

Gets the number of items in a row of the ribbon color button’s gallery display.

int GetColumns() const;  

Return Value

Returns the number of icons in each row.

Remarks

CMFCRibbonColorButton::GetHighlightedColor

Returns the color of the currently selected element on the pop-up color palette.

COLORREF GetHighlightedColor() const;  

Return Value

The color of currently selected element on the pop-up color palette.

CMFCRibbonColorButton::RemoveAllColorGroups

Removes all color groups from the regular color area.

void RemoveAllColorGroups();

CMFCRibbonColorButton::SetColor

Selects a color from the regular color area.

void SetColor(COLORREF color);

Parameters

[in] color
A color to set.

CMFCRibbonColorButton::SetColorBoxSize

Sets the size of all the color elements that appear on the color bar.

void SetColorBoxSize(CSize sizeBox);

Parameters

[in] sizeBox
The new size of the color buttons in the color palette.

CMFCRibbonColorButton::SetColorName

Sets a new name for a specified color.

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

Parameters

[in] color
The RGB value of a color.

[in] strName
The new name for the specified color.

Remarks

Because it calls CMFCColorBar::SetColorName, this method changes the name of the specified color in all CMFCColorBar objects in your application.

CMFCRibbonColorButton::SetColumns

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

void SetColumns(int nColumns);

Parameters

[in] nColumns
The number of color icons to display in each row.

Remarks

CMFCRibbonColorButton::SetDocumentColors

Specifies a list of RGB values to display in the document color area.

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

Parameters

[in] lpszLabel
The text to be displayed with the document colors.

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

CMFCRibbonColorButton::SetPalette

Specifies the standard colors to display in the color table that the color button displays.

void SetPalette(CPalette* pPalette);

Parameters

[in] pPalette
A pointer to a color palette.

Remarks

CMFCRibbonColorButton::UpdateColor

Called by the framework when the user selects a color from the color table displayed when the user clicks the color button.

void UpdateColor(COLORREF color);

Parameters

[in] color
A color selected by the user.

Remarks

The CMFCRibbonColorButton::UpdateColor method 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 CMFCRibbonColorButton::GetColor method to retrieve the selected color.

See Also

Hierarchy Chart
Classes
CMFCRibbonGallery Class