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
| Name | Description |
|---|---|
| CMFCRibbonColorButton::CMFCRibbonColorButton |
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
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
lpszName
[in] The group name.
lstColors
[in] The list of colors.
bContiguousColumns
[in] 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
nID
[in] Specifies the command ID of the command to execute when a user clicks the button.
lpszText
[in] Specifies the text to appear on the button.
nSmallImageIndex
[in] The zero-based index of the small image to appear on the button.
color
[in] The color of the button (defaults to black).
bSimpleButtonLook
[in] If TRUE, the button is drawn as a simple rectangle.
nLargeImageIndex
[in] 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
lpszLabel
[in] The label for the Automatic button.
colorAutomatic
[in] An RGB value that specifies the Automatic button's default color.
bEnable
[in] TRUE if the Automatic button is enabled; FALSE if it is disabled.
lpszToolTip
[in] The tooltip of the Automatic button.
bOnTop
[in] Specifies whether the Automatic button is at the top, before color palette.
bDrawBorder
[in] 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
color
[in] 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
sizeBox
[in] 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
color
[in] The RGB value of a color.
strName
[in] 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
nColumns
[in] 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
lpszLabel
[in] The text to be displayed with the document colors.
lstColors
[in] 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
pPalette
[in] 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
color
[in] 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.