Edit

CMFCColorBar Class

  • Article

The CMFCColorBar class represents a docking control bar that can select colors in a document or application.

Syntax

class CMFCColorBar : public CMFCPopupMenuBar

Members

Protected Constructors

Name Description
CMFCColorBar::CMFCColorBar Constructs a CMFCColorBar object.

Public Methods

Name Description
CMFCColorBar::ContextToSize Calculates the vertical and horizontal margins that are required to contain the buttons on the color bar control and then adjusts the location of those buttons.
CMFCColorBar::CreateControl Creates a color bar control window, attaches it to the CMFCColorBar object, and resizes the control to contain the specified palette of colors.
CMFCColorBar::Create Creates a color bar control window and attaches it to the CMFCColorBar object.
CMFCColorBar::EnableAutomaticButton Shows or hides the automatic button.
CMFCColorBar::EnableOtherButton Enables or disables the display of a dialog box that lets the user select more colors.
CMFCColorBar::GetColor Retrieves the currently selected color.
CMFCColorBar::GetCommandID Retrieves the command ID of the current color bar control.
CMFCColorBar::GetHighlightedColor Retrieves the color that signifies that a color button has the focus; that is, the button is hot.
CMFCColorBar::GetHorzMargin Retrieves the horizontal margin, which is the space between the left or right color cell and the client area boundary.
CMFCColorBar::GetVertMargin Retrieves the vertical margin, which is the space between the top or bottom color cell and the client area boundary.
CMFCColorBar::IsTearOff Indicates whether the current color bar is dockable.
CMFCColorBar::SetColor Sets the color that is currently selected.
CMFCColorBar::SetColorName Sets a new name for a specified color.
CMFCColorBar::SetCommandID Sets a new command ID for a color bar control.
CMFCColorBar::SetDocumentColors Sets the list of colors that are used in the current document.
CMFCColorBar::SetHorzMargin Sets the horizontal margin, which is the space between the left or right color cell and the client area boundary.
CMFCColorBar::SetVertMargin Sets the vertical margin, which is the space between the top or bottom color cell and the client area boundary.

Protected Methods

Name Description
CMFCColorBar::AdjustLocations Adjusts the positions of the color buttons on the color bar control.
CMFCColorBar::AllowChangeTextLabels Indicates whether the text label of color buttons can change.
CMFCColorBar::AllowShowOnList Indicates whether the color bar control object can appear in a toolbar list during the customization process.
CMFCColorBar::CalcSize Called by the framework as part of the layout calculation process.
CMFCColorBar::CreatePalette Initializes a palette with the colors in a specified array of colors.
CMFCColorBar::GetColorGridSize Calculates the number of rows and columns in the grid of a color bar control.
CMFCColorBar::GetExtraHeight Calculates the additional height that the current color bar requires to display miscellaneous user interface elements such as the Other button, document colors, and so on.
CMFCColorBar::InitColors Initializes an array of colors with the colors in a specified palette or the system default palette.
CMFCColorBar::OnKey Called by the framework when a user presses a keyboard button.
CMFCColorBar::OnSendCommand Called by the framework to close a hierarchy of popup controls.
CMFCColorBar::OnUpdateCmdUI Called by the framework to enable or disable a user-interface item of a color bar control before the item is displayed.
CMFCColorBar::OpenColorDialog Opens a color dialog box.
CMFCColorBar::Rebuild Completely redraws the color bar control.
CMFCColorBar::SelectPalette Sets the logical palette of the specified device context to the palette of the parent button of the current color bar control.
CMFCColorBar::SetPropList Sets the m_pWndPropList protected data member to the specified pointer to a property grid control.
CMFCColorBar::ShowCommandMessageString Requests the frame window that owns the color bar control to update the message line in the status bar.

Protected Data Members

Name Description
m_bInternal A Boolean field that determines whether mouse events are processed. Typically, mouse events are processed when this field is TRUE and customization mode is FALSE.
m_bIsEnabled A Boolean that indicates whether a control is enabled.
m_bIsTearOff A Boolean that indicates whether the color bar control supports docking.
m_BoxSize A CSize object that specifies the size of a cell in a color bar grid.
m_bShowDocColorsWhenDocked A Boolean that indicates whether to show document colors when the color bar is docked. For more information, see CMFCColorBar::SetDocumentColors.
m_bStdColorDlg A Boolean that indicates whether to show the standard system color dialog box or the CMFCColorDialog dialog box. For more information, see CMFCColorBar::EnableOtherButton.
m_ColorAutomatic A COLORREF that stores the current automatic color. For more information, see CMFCColorBar::EnableOtherButton.
m_ColorNames A CMap object that associates a set of RGB colors with their names.
m_colors A CArray of COLORREF values that contains the colors that are displayed in the color bar control.
m_ColorSelected A COLORREF value that is the color that the user has currently selected from the color bar control.
m_lstDocColors A CList of COLORREF values that contains the colors that are currently used in a document.
m_nCommandID An unsigned integer that is the command ID of a color button.
m_nHorzMargin An integer that is the horizontal margin between the color buttons in a grid of colors.
m_nHorzOffset An integer that is the horizontal offset to the center of the color button. This value is significant if the button displays text or an image in addition to a color.
m_nNumColumns An integer that is the number of columns in a color bar control grid of colors.
m_nNumColumnsVert An integer that is the number of columns in a vertically oriented grid of colors.
m_nNumRowsHorz An integer that is the number of columns in a horizontally oriented grid of colors.
m_nRowHeight An integer that is the height of a row of color buttons in a grid of colors.
m_nVertMargin An integer that is the vertical margin between the color buttons in a grid of colors.
m_nVertOffset An integer that is the vertical offset to the center of the color button. This value is significant if the button displays text or an image in addition to a color.
m_Palette A CPalette of the colors that are used in the color bar control.
m_pParentBtn A pointer to a CMFCColorButton object that is the parent of the current button. This value is significant if the color button is in a hierarchy of toolbar controls or is in a color property grid control.
m_pParentRibbonBtn A pointer to a CMFCRibbonColorButton object that is on the ribbon and is the parent button of the current button. This value is significant if the color button is in a hierarchy of toolbar controls or is in a color property grid control.
m_pWndPropList A pointer to a CMFCPropertyGridCtrl object.
m_strAutoColor A CString that is the text that is displayed on the Automatic button. For more information, see CMFCColorBar::EnableAutomaticButton.
m_strDocColors A CString that is the text that is displayed on the document colors button. For more information, see CMFCColorBar::SetDocumentColors.
m_strOtherColor A CString that is the text that is displayed on the other button. For more information, see CMFCColorBar::EnableOtherButton.

Remarks

Usually, you do not create a CMFCColorBar object directly. Instead, the CMFCColorMenuButton Class (used in menus and toolbars) or the CMFCColorButton Class creates the CMFCColorBar object.

The CMFCColorBar class provides the following functionality:

  • Automatically adjusts the list of document colors.

  • Saves and restores its state, together with the document state.

  • Manages the "automatic" button.

  • Uses the CMFCColorPickerCtrl Class control to select a custom color.

  • Supports a "tear-off" state (if it is created by using the CMFCColorMenuButton Class).

To incorporate the CMFCColorBar functionality into your application:

  1. Create a regular menu button and assign it an ID, for example ID_CHAR_COLOR.

  2. In your frame window class, override the CFrameWndEx::OnShowPopupMenu method and replace the regular menu button with a CMFCColorMenuButton Class object (by calling CMFCToolBar::ReplaceButton).

  3. Set all the styles and enable or disable the features of the CMFCColorBar object during CMFCColorMenuButton Class creation. The CMFCColorMenuButton object dynamically creates the CMFCColorBar object after the framework calls the CreatePopupMenu method.

When the user clicks a color bar control button, the framework uses the ON_COMMAND macro to notify the parent of the color bar control. In the macro, the command ID parameter is the value that you assigned to the color bar control button in step 1 (ID_CHAR_COLOR in this example). For more information, see the CMFCColorMenuButton Class, CMFCColorButton Class, CMFCColorPickerCtrl Class, CFrameWndEx Class, and CMFCToolBar Class classes.

Example

The following example demonstrates how to configure a color bar by using various methods in the CMFCColorBar class. The methods set the horizontal and vertical margins, enable the other button, create a color bar control window, and sets the currently selected color. This example is part of the New Controls sample.

CMFCColorBar m_wndColorBar;

// set the margins
m_wndColorBar.SetHorzMargin(0);
m_wndColorBar.SetVertMargin(0);
// enable the display of a dialog box that
// lets the user select more colors
m_wndColorBar.EnableOtherButton(_T("Other..."));
// create a color bar control window
m_wndColorBar.CreateControl(this, rectColorBar, IDC_COLORBAR, 5 /* columns */);
// set the currently selected color
m_wndColorBar.SetColor(RGB(255, 0, 0));

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCBaseToolBar

CMFCToolBar

CMFCPopupMenuBar

CMFCColorBar

Requirements

Header: afxcolorbar.h

CMFCColorBar::AdjustLocations

Adjusts the positions of the color buttons on the color bar control.

virtual void AdjustLocations();

Remarks

This method is called by the framework during WM_SIZE message processing.

CMFCColorBar::AllowChangeTextLabels

Indicates whether the text label of color buttons can change.

virtual BOOL AllowChangeTextLabels() const;

Return Value

Always FALSE.

Remarks

By default, this method always returns FALSE, which means text labels cannot be modified. Override this method to enable modifying text labels.

CMFCColorBar::AllowShowOnList

Indicates whether the color bar control object can appear in a toolbar list during the customization process.

virtual BOOL AllowShowOnList() const;

Return Value

Always TRUE.

Remarks

By default, this method always returns TRUE, which means the framework can display the color bar control during the customization process. Override this method to implement a different behavior.

CMFCColorBar::CalcSize

Called by the framework as part of the layout calculation process.

virtual CSize CalcSize(BOOL bVertDock);

Parameters

bVertDock
[in] TRUE to specify that the color bar control is docked vertically; FALSE to specify that the color bar control is docked horizontally.

Return Value

The size of the array of color buttons in a color bar control.

CMFCColorBar::CMFCColorBar

Constructs a CMFCColorBar object.

CMFCColorBar(
    const CArray<COLORREF,COLORREF>& colors,
    COLORREF color,
    LPCTSTR lpszAutoColor,
    LPCTSTR lpszOtherColor,
    LPCTSTR lpszDocColors,
    CList<COLORREF,COLORREF>& lstDocColors,
    int nColumns,
    int nRowsDockHorz,
    int nColDockVert,
    COLORREF colorAutomatic,
    UINT nCommandID,
    CMFCColorButton* pParentBtn);

CMFCColorBar(
    const CArray<COLORREF,COLORREF>& colors,
    COLORREF color,
    LPCTSTR lpszAutoColor,
    LPCTSTR lpszOtherColor,
    LPCTSTR lpszDocColors,
    CList<COLORREF,COLORREF>& lstDocColors,
    int nColumns,
    COLORREF colorAutomatic,
    UINT nCommandID,
    CMFCRibbonColorButton* pParentRibbonBtn);

CMFCColorBar(
    CMFCColorBar& src,
    UINT uiCommandID);

Parameters

colors
[in] An array of colors that the framework displays on the color bar control.

color
[in] The initially selected color.

lpszAutoColor
[in] The text label of the automatic (default) color button, or NULL.

The standard label for the automatic button is Automatic.

lpszOtherColor
[in] The text label of the other button, which displays more color choices, or NULL.

The standard label for the other button is More Colors....

lpszDocColors
[in] The text label of the document colors button. The document colors palette lists all the colors that the document currently uses.

lstDocColors
[in] A list of colors that the document currently uses.

nColumns
[in] The number of columns that the array of colors has.

nRowsDockHorz
[in] The number of rows that the color bar has when it is docked horizontally.

nColDockVert
[in] The number of columns that the color bar has when it is docked vertically.

colorAutomatic
[in] The default color that the framework applies when you click the automatic button.

nCommandID
[in] The color bar control command ID.

pParentBtn
[in] A pointer to a parent button.

src
[in] An existing CMFCColorBar object to be copied into the new CMFCColorBar object.

uiCommandID
[in] The command ID.

CMFCColorBar::ContextToSize

Calculates the vertical and horizontal margins that are required to contain the buttons on the color bar control, and adjusts the location of those buttons.

void ContextToSize(
    BOOL bSquareButtons = TRUE,
    BOOL bCenterButtons = TRUE);

Parameters

bSquareButtons
[in] TRUE to specify that the shape of the buttons on a color bar control are square; otherwise, FALSE. The default value is TRUE.

bCenterButtons
[in] TRUE to specify that the content on the face of a color bar control button is centered; otherwise, FALSE. The default value is TRUE.

Remarks

CMFCColorBar::Create

Creates a color bar control window and attaches it to the CMFCColorBar object.

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle,
    UINT nID,
    CPalette* pPalette=NULL,
    int nColumns=0,
    int nRowsDockHorz=0,
    int nColDockVert=0);

Parameters

pParentWnd
[in] Pointer to the parent window.

dwStyle
[in] A bitwise combination (OR) of window styles.

nID
[in] The command ID.

pPalette
[in] Pointer to a palette of colors. The default is NULL.

nColumns
[in] The number of columns in the color bar control. The default is 0.

nRowsDockHorz
[in] The number of rows in the color bar control when it is docked horizontally. The default is 0.

nColDockVert
[in] The number of columns in the color bar control when it is docked vertically. The default is 0.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

To construct a CMFCColorBar object, call the class constructor then this method. The Create method creates the Windows control and initializes a list of colors.

CMFCColorBar::CreateControl

Creates a color bar control window, attaches it to the CMFCColorBar object, and resizes the control window to contain the specified palette of colors.

virtual BOOL CreateControl(
    CWnd* pParentWnd,
    const CRect& rect,
    UINT nID,
    int nColumns=-1,
    CPalette* pPalette=NULL);

Parameters

pParentWnd
[in] Pointer to the parent window. Cannot be NULL.

rect
[in] A bounding rectangle that specifies where to draw the color bar control.

nID
[in] The control ID.

nColumns
[in] The ideal number of columns in the color bar control. This method modifies that number to fit the specified palette of colors. The default is -1, which means this parameter is not specified.

pPalette
[in] Pointer to a palette of colors, or NULL. If this parameter is NULL, this method calculates the size of the color bar control as if 20 colors were specified. The default is NULL.

Return Value

TRUE if this method succeeds; otherwise FALSE.

Remarks

This method uses the rect, nColumns, and pPalette parameters to calculate the appropriate number or rows and columns in the color bar control, and then calls the CMFCColorBar::Create method.

CMFCColorBar::CreatePalette

Initializes a palette with the colors in a specified array of colors.

static BOOL CreatePalette(
    const CArray<COLORREF, COLORREF>& arColors,
    CPalette& palette);

Parameters

arColors
[in] An array of colors.

palette
[in] A palette of colors.

Return Value

TRUE if this method is successful; otherwise, FALSE.

CMFCColorBar::EnableAutomaticButton

Shows or hides the automatic button.

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

Parameters

lpszLabel
[in] The text label of the automatic (default) color button, or NULL.

The standard label for the automatic button is Automatic.

colorAutomatic
[in] The default color that the framework applies when you click the automatic button.

bEnable
[in] TRUE to enable the automatic button; FALSE to disable the automatic button. The default value is TRUE.

Remarks

The text label of the automatic button is deleted if the lpszLabel parameter is NULL or the bEnable parameter is FALSE.

CMFCColorBar::EnableOtherButton

Enables or disables the display of a dialog box that lets the user select more colors.

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

Parameters

lpszLabel
[in] The text label of the other button, which displays more color choices, or NULL.

The standard label for this button is More Colors....

bAltColorDlg
[in] TRUE to display the CMFCColorDialog dialog box; FALSE to display the standard CColorDialog dialog box. The default value is TRUE.

bEnable
[in] TRUE to enable the button; FALSE to disable the button. The default value is TRUE.

CMFCColorBar::GetColor

Retrieves the currently selected color.

COLORREF GetColor() const;

Return Value

The currently selected color.

CMFCColorBar::GetColorGridSize

Calculates the number of rows and columns in the grid of a color bar control.

CSize GetColorGridSize(BOOL bVertDock) const;

Parameters

bVertDock
[in] TRUE to perform the calculation for a vertically docked color bar control; otherwise, perform the calculation for a horizontally docked control.

Return Value

A CSize object whose cx component contains the number of columns and whose cy component contains the number of rows.

CMFCColorBar::GetCommandID

Retrieves the command ID of the current color bar control.

UINT GetCommandID() const;

Return Value

A command ID.

Remarks

When the user selects a new color, the framework sends the command ID in a WM_COMMAND message to notify the parent of the CMFCColorBar object.

CMFCColorBar::GetExtraHeight

Calculates the additional height that the current color bar requires to display miscellaneous user interface elements, such as the Other button or document colors.

int GetExtraHeight(int nNumColumns) const;

Parameters

nNumColumns
[in] If the color bar control contains document colors, the number of columns to display in the grid of document colors. Otherwise, this value is not used.

Return Value

The calculated extra height that is required.

CMFCColorBar::GetHighlightedColor

Retrieves the color that signifies that a color button has the focus; that is, the button is hot.

COLORREF GetHighlightedColor() const;

Return Value

An RGB value.

Remarks

CMFCColorBar::GetHorzMargin

Retrieves the horizontal margin, which is the space between the left or right color cell and the client area boundary.

int GetHorzMargin();

Return Value

The horizontal margin.

CMFCColorBar::GetVertMargin

Retrieves the vertical margin, which is the space between the top or bottom color cell and the client area boundary.

int GetVertMargin() const;

Return Value

The vertical margin.

CMFCColorBar::InitColors

Initializes an array of colors with the colors in a specified palette, or with the system default palette.

static int InitColors(
    CPalette* pPalette,
    CArray<COLORREF, COLORREF>& arColors);

Parameters

pPalette
[in] A pointer to a palette object, or NULL. If this parameter is NULL, this method uses the default palette of the operating system.

arColors
[in] An array of colors.

Return Value

The number of elements in the array of colors.

CMFCColorBar::IsTearOff

Indicates whether the current color bar is dockable.

BOOL IsTearOff() const;

Return Value

TRUE if the current color bar control is dockable; otherwise, FALSE.

Remarks

If the color bar control is dockable, it can be torn off a control bar and docked at another location.

CMFCColorBar::OnKey

Called by the framework when a user presses a keyboard button.

virtual BOOL OnKey(UINT nChar);

Parameters

nChar
[in] The virtual-key code for the key that a user pressed.

Return Value

TRUE if this method processes the specified key; otherwise, FALSE.

CMFCColorBar::OnSendCommand

Called by the framework to close a hierarchy of pop-up controls.

virtual BOOL OnSendCommand(const CMFCToolBarButton* pButton);

Parameters

pButton
[in] Pointer to a control that resides on a toolbar.

Return Value

TRUE if this method is successful; otherwise, FALSE.

CMFCColorBar::OnUpdateCmdUI

Called by the framework to enable or disable a user-interface item of a color bar control before the item is displayed.

virtual void OnUpdateCmdUI(
    CFrameWnd* pTarget,
    BOOL bDisableIfNoHndler);

Parameters

pTarget
[in] Pointer to a window that contains a user-interface item to update.

bDisableIfNoHndler
[in] TRUE to disable the user-interface item if no handler is defined in a message map; otherwise, FALSE.

Remarks

When a user of your application clicks a user-interface item, the item must know whether it should be displayed as enabled or disabled. The target of the command message provides this information by implementing an ON_UPDATE_COMMAND_UI command handler. Use this method to help process the command. For more information, see CCmdUI Class.

CMFCColorBar::OpenColorDialog

Opens a color dialog box.

virtual BOOL OpenColorDialog(
    const COLORREF colorDefault,
    COLORREF& colorRes);

Parameters

colorDefault
[in] The color that is selected by default when the color dialog box opens.

colorRes
[out] The color that a user selected.

Return Value

TRUE if the user selected a color; FALSE if the user canceled the color dialog box.

Remarks

CMFCColorBar::Rebuild

Completely redraws the color bar control.

virtual void Rebuild();

CMFCColorBar::SelectPalette

Sets the logical palette of the specified device context to the palette of the parent button of the current color bar control.

CPalette* SelectPalette(CDC* pDC);

Parameters

pDC
[in] Pointer to the device context of the parent button of the current color bar control.

Return Value

Pointer to the palette that is replaced by the palette of the parent button of the current color bar control.

CMFCColorBar::SetColor

Sets the color that is currently selected.

void SetColor(COLORREF color);

Parameters

color
[in] An RGB color value.

CMFCColorBar::SetColorName

Sets a new name for a specified color.

static void 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

This method changes the name of the specified color in all CMFCColorBar objects in your application.

CMFCColorBar::SetCommandID

Sets a new command ID for a color bar control.

void SetCommandID(UINT nCommandID);

Parameters

nCommandID
[in] A command ID.

Remarks

Call this method to modify the command ID of a color bar control and to notify the parent window of the control that the ID has changed.

CMFCColorBar::SetDocumentColors

Sets the list of colors that are used in the current document.

void SetDocumentColors(
    LPCTSTR lpszCaption,
    CList<COLORREF,COLORREF>& lstDocColors,
    BOOL bShowWhenDocked=FALSE);

Parameters

lpszCaption
[in] A caption that is displayed when the color bar control is not docked.

lstDocColors
[in] A list of colors that replaces the current document colors.

bShowWhenDocked
[in] TRUE to show document colors when the color bar control is docked; otherwise, FALSE. The default value is FALSE.

Remarks

Document colors are the colors that are currently used in a document. The framework automatically maintains a list of document colors, but you can use this method to modify the list.

CMFCColorBar::SetHorzMargin

Sets the horizontal margin, which is the space between the left or right color cell and the boundary of the client area.

void SetHorzMargin(int nHorzMargin);

Parameters

nHorzMargin
[in] The horizontal margin, in pixels.

Remarks

By default, the CMFCColorBar::CMFCColorBar constructor sets the horizontal margin to 4 pixels.

CMFCColorBar::SetPropList

Sets the m_pWndPropList protected data member to the specified pointer to a property grid control.

void SetPropList(CMFCPropertyGridCtrl* pWndList);

Parameters

pWndList
[in] Pointer to property grid control object.

CMFCColorBar::SetVertMargin

Sets the vertical margin, which is the space between the top or bottom color cell and the client area boundary.

void SetVertMargin(int nVertMargin);

Parameters

nVertMargin
[in] The vertical margin, in pixels.

Remarks

By default, the CMFCColorBar::CMFCColorBar constructor sets the vertical margin to 4 pixels.

CMFCColorBar::ShowCommandMessageString

Requests the frame window that owns the color bar control to update the message line in the status bar.

virtual void ShowCommandMessageString(UINT uiCmdId);

Parameters

uiCmdId
[in] A command ID. (This parameter is ignored.)

Remarks

This method sends the WM_SETMESSAGESTRING message to the owner of the color bar control.

See also

Hierarchy Chart
Classes