CMFCColorBar Class

發行項
07/25/2011

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

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	Initalizes 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	An 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:

Create a regular menu button and assign it an ID, for example ID_CHAR_COLOR.
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).
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));