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

The CMFCButton class adds functionality to the CButton class such as aligning button text, combining button text and an image, selecting a cursor, and specifying a tool tip.

class CMFCButton : public CButton  

Public Constructors

NameDescription
CMFCButton::CMFCButtonDefault constructor.
CMFCButton::~CMFCButtonDestructor.

Public Methods

NameDescription
CMFCButton::CleanUpResets internal variables and frees allocated resources such as images, bitmaps, and icons.
CMFCButton::CreateObjectUsed by the framework to create a dynamic instance of this class type.
CMFCButton::DrawItemCalled by the framework when a visual aspect of an owner-drawn button has changed. (Overrides CButton::DrawItem.)
CMFCButton::EnableFullTextTooltipSpecifies whether to display the full text of a tooltip in a large tooltip window or a truncated version of the text in a small tooltip window.
CMFCButton::EnableMenuFontSpecifies whether the button text font is the same as the application menu font.
CMFCButton::EnableWindowsThemingSpecifies whether the style of the button border corresponds to the current Windows theme.
CMFCButton::GetThisClassUsed by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CMFCButton::GetToolTipCtrlReturns a reference to the underlying tooltip control.
CMFCButton::IsAutoCheckIndicates whether a check box or radio button is an automatic button.
CMFCButton::IsAutorepeatCommandModeIndicates whether a button is set to auto-repeat mode.
CMFCButton::IsCheckBoxIndicates whether a button is a check box button.
CMFCButton::IsCheckedIndicates whether the current button is checked.
CMFCButton::IsHighlightedIndicates whether a button is highlighted.
CMFCButton::IsPressedIndicates whether a button is pushed and highlighted.
CMFCButton::IsPushedIndicates whether a button is pushed.
CMFCButton::IsRadioButtonIndicates whether a button is a radio button.
CMFCButton::IsWindowsThemingEnabledIndicates whether the style of the button border corresponds to the current Windows theme.
CMFCButton::OnDrawParentBackgroundDraws the background of a button's parent in the specified area. (Overrides AFX_GLOBAL_DATA::DrawParentBackground
CMFCButton::PreTranslateMessageTranslates window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. (Overrides CWnd::PreTranslateMessage.)
CMFCButton::SetAutorepeatModeSets a button to auto-repeat mode.
CMFCButton::SetCheckedImageSets the image for a checked button.
CMFCButton::SetFaceColorSets the background color for the button text.
CMFCButton::SetImageSets the image for a button.
CMFCButton::SetMouseCursorSets the cursor image.
CMFCButton::SetMouseCursorHandSets the cursor to the image of a hand.
CMFCButton::SetStdImageUses a CMenuImages object to set the button image.
CMFCButton::SetTextColorSets the color of the button text for a button that is not selected.
CMFCButton::SetTextHotColorSets the color of the button text for a button that is selected.
CMFCButton::SetTooltipAssociates a tooltip with a button.
CMFCButton::SizeToContentResizes a button to contain its button text and image.

Protected Methods

NameDescription
CMFCButton::OnDrawCalled by the framework to draw a button.
CMFCButton::OnDrawBorderCalled by the framework to draw the border of a button.
CMFCButton::OnDrawFocusRectCalled by the framework to draw the focus rectangle for a button.
CMFCButton::OnDrawTextCalled by the framework to draw the button text.
CMFCButton::OnFillBackgroundCalled by the framework to draw the background of the button text.
CMFCButton::SelectFontRetrieves the font that is associated with the specified device context.

Data Members

NameDescription
CMFCButton::m_bDrawFocusIndicates whether to draw a focus rectangle around a button.
CMFCButton::m_bHighlightCheckedIndicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it.
CMFCButton::m_bRightImageIndicates whether to display an image on the right side of the button.
CMFCButton::m_bTransparentIndicates whether the button is transparent.
CMFCButton::m_nAlignStyleSpecifies the alignment of the button text.
CMFCButton::m_nFlatStyleSpecifies the style of the button, such as borderless, flat, semi-flat, or 3D.

Other types of buttons are derived from the CMFCButton class, such as the CMFCURLLinkButton class, which supports hyperlinks, and the CMFCColorButton class, which supports a color picker dialog box.

The style of a CMFCButton object can be 3D, flat, semi-flat or no border. Button text can be aligned at the left, top, or center of a button. At run time, you can control whether the button displays text, an image, or text and an image. You can also specify that a particular cursor image be displayed when the cursor hovers over a button.

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

To handle notification messages in a dialog box application, add a message map entry and an event handler for each notification. The notifications sent by a CMFCButton object are the same as those sent by a CButton object.

The following example demonstrates how to configure the properties of the button by using various methods in the CMFCButton class. The example is part of the New Controls sample.

	CMFCButton m_Button;

	// int m_iImage
	// IDB_BTN1_32, IDB_BTN1_HOT_32, IDB_BTN1, IDB_BTN1_HOT are int macros that are #define.
	if (m_iImage == 1) 
	{
		m_Button.SetImage((HBITMAP) NULL);
	}
	else
	{
		m_Button.SetImage(IDB_BTN1_32, IDB_BTN1_HOT_32);
	}

	// int m_iImage
	if (m_iImage == 0)
	{
		m_Button.SetWindowText(_T(""));
	}
	else
	{
		m_Button.SetWindowText(_T("Button"));
	}

	// Resize the button.
	m_Button.SizeToContent();
	m_Button.EnableFullTextTooltip(true);
	// Use the application menu font at the button text font.
	m_Button.EnableMenuFont();
	// Use the current Windows theme to draw the button borders.
	m_Button.EnableWindowsTheming(true);
	// Set the button to auto-repeat mode.
	m_Button.SetAutorepeatMode();
	// Set the background color for the button text.
	m_Button.SetFaceColor(RGB(255,0,0),true);
	m_Button.SetTextColor(RGB(0,0,255));
	// Set the tooltip of the button.
	m_Button.SetTooltip(_T("this is a button!"));

CObject

CCmdTarget

CWnd

CButton

CMFCButton

Header: afxbutton.h

Resets internal variables and frees allocated resources such as images, bitmaps, and icons.

virtual void CleanUp();

Specifies whether to display the full text of a tooltip in a large tooltip window or a truncated version of the text in a small tooltip window.

void EnableFullTextTooltip(BOOL bOn=TRUE);

Parameters

[in] bOn
TRUE to display all of the text; FALSE to display truncated text.

Remarks

Specifies whether the button text font is the same as the application menu font.

void EnableMenuFont(
    BOOL bOn=TRUE,  
    BOOL bRedraw=TRUE);

Parameters

[in] bOn
TRUE to use the application menu font as the button text font; FALSE to use the system font. The default is TRUE.

[in] bRedraw
TRUE to immediately redraw the screen; otherwise, FALSE. The default is TRUE.

Remarks

If you do not use this method to specify the button text font, you can specify the font with the CWnd::SetFont method. If you do not specify a font at all, the framework sets a default font.

Specifies whether the style of the button border corresponds to the current Windows theme.

static void EnableWindowsTheming(BOOL bEnable = TRUE);

Parameters

[in] bEnable
TRUE to use the current Windows theme to draw button borders; FALSE to not use the Windows theme. The default is TRUE.

Remarks

This method affects all buttons in your application that are derived from the CMFCButton class.

Returns a reference to the underlying tooltip control.

CToolTipCtrl& GetToolTipCtrl();

Return Value

A reference to the underlying tooltip control.

Remarks

Indicates whether a check box or radio button is an automatic button.

BOOL IsAutoCheck() const;  

Return Value

TRUE if the button has style BS_AUTOCHECKBOX or BS_AUTORADIOBUTTON; otherwise, FALSE.

Remarks

Indicates whether a button is set to auto-repeat mode.

BOOL IsAutorepeatCommandMode() const;  

Return Value

TRUE if the button is set to auto-repeat mode; otherwise, FALSE.

Remarks

Use the CMFCButton::SetAutorepeatMode method to set a button to auto-repeat mode.

Indicates whether a button is a check box button.

BOOL IsCheckBox() const;  

Return Value

TRUE if the button has either BS_CHECKBOX or BS_AUTOCHECKBOX style; otherwise, FALSE.

Remarks

Indicates whether the current button is checked.

BOOL IsChecked() const;  

Return Value

TRUE if the current button is checked; otherwise, FALSE.

Remarks

The framework uses different ways to indicate that different kinds of buttons are checked. For example, a radio button is checked when it contains a dot; a check box is checked when it contains an X.

Indicates whether a button is highlighted.

BOOL IsHighlighted() const;  

Return Value

TRUE if the button is highlighted; otherwise, FALSE.

Remarks

A button becomes highlighted when the mouse hovers over the button.

Indicates whether a button is pushed and highlighted.

BOOL IsPressed() const;  

Return Value

TRUE if the button is pressed; otherwise, FALSE.

Remarks

Indicates whether a button is pushed.

BOOL IsPushed() const;  

Return Value

TRUE if the button is pushed; otherwise, FALSE.

Remarks

Indicates whether a button is a radio button.

BOOL IsRadioButton() const;  

Return Value

TRUE if the button style is BS_RADIOBUTTON or BS_AUTORADIOBUTTON; otherwise, FALSE.

Remarks

Indicates whether the style of the button border corresponds to the current Windows theme.

static BOOL IsWindowsThemingEnabled();

Return Value

TRUE if the style of the button border corresponds to the current Windows theme; otherwise, FALSE.

Indicates whether to draw a focus rectangle around a button.

BOOL m_bDrawFocus;  

Remarks

Set the m_bDrawFocus member to TRUE to specify that the framework will draw a focus rectangle around the button's text and image if the button receives focus.

The CMFCButton constructor initializes this member to TRUE.

Indicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it.

BOOL m_bHighlightChecked;  

Remarks

Set the m_bHighlightChecked member to TRUE to specify that the framework will highlight a BS_CHECKBOX-style button when the mouse hovers over it.

Indicates whether to display an image on the right side of the button.

BOOL m_bRightImage;  

Remarks

Set the m_bRightImage member to TRUE to specify that the framework will display the button's image to the right of the button's text label.

Indicates whether the button is transparent.

BOOL m_bTransparent;  

Remarks

Set the m_bTransparent member to TRUE to specify that the framework will make the button transparent. The CMFCButton constructor initializes this member to FALSE.

Specifies the alignment of the button text.

AlignStyle m_nAlignStyle;  

Remarks

Use one of the following CMFCButton::AlignStyle enumeration values to specify the alignment of the button text:

ValueDescription
ALIGN_CENTER(Default) Aligns the button text to the center of the button.
ALIGN_LEFTAligns the button text to the left side of the button.
ALIGN_RIGHTAligns the button text to the right side of the button.

The CMFCButton constructor initializes this member to ALIGN_CENTER.

Specifies the style of the button, such as borderless, flat, semi-flat, or 3D.

FlatStyle  m_nFlatStyle;  

Remarks

The following table lists the CMFCButton::m_nFlatStyle enumeration values that specify the appearance of a button.

ValueDescription
BUTTONSTYLE_3D(Default) The button appears to have high, three-dimensional sides. When the button is clicked, the button appears to be pressed into a deep indentation.
BUTTONSTYLE_FLATWhen the mouse does not pause over the button, the button appears to be two-dimensional and does not have raised sides. When the mouse pauses over the button, the button appears to have low, three-dimensional sides. When the button is clicked, the button appears to be pressed into a shallow indentation.
BUTTONSTYLE_SEMIFLATThe button appears to have low, three-dimensional sides. When the button is clicked, the button appears to be pressed into a deep indentation.
BUTTONSTYLE_NOBORDERSThe button does not have raised sides and always appears two-dimensional. The button does not appear to be pressed into an indentation when it is clicked.

The CMFCButton constructor initializes this member to BUTTONSTYLE_3D.

Example

The following example demonstrates how to set the values of the m_nFlatStyle member variable in the CMFCButton class. This example is part of the New Controls sample.

	CMFCButton m_Button;

	//int m_iBorderStyle
	switch (m_iBorderStyle)
	{
	case 0:
		m_Button.m_nFlatStyle = CMFCButton::BUTTONSTYLE_FLAT;
		break;

	case 1:
		m_Button.m_nFlatStyle = CMFCButton::BUTTONSTYLE_SEMIFLAT;
		break;

	case 2:
		m_Button.m_nFlatStyle = CMFCButton::BUTTONSTYLE_3D;
	}

Called by the framework to draw a button.

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

Parameters

[in] pDC
A pointer to a device context.

[in] rect
A reference to a rectangle that bounds the button.

[in] uiState
The current button state. For more information, see the itemState member of the DRAWITEMSTRUCT Structure topic.

Remarks

Override this method to use your own code to draw a button.

Called by the framework to draw the border of a button.

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

Parameters

[in] pDC
A pointer to a device context.

[in] rectClient
A reference to a rectangle that bounds the button.

[in] uiState
The current button state. For more information, see the itemState member of the DRAWITEMSTRUCT Structure topic.

Remarks

Override this method to use your own code to draw the border.

Called by the framework to draw the focus rectangle for a button.

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

Parameters

[in] pDC
A pointer to a device context.

[in] rectClient
A reference to a rectangle that bounds the button.

Remarks

Override this method to use your own code to draw the focus rectangle.

Called by the framework to draw the button text.

virtual void OnDrawText(
    CDC* pDC,  
    const CRect& rect,  
    const CString& strText,  
    UINT uiDTFlags,  
    UINT uiState);

Parameters

[in] pDC
A pointer to a device context.

[in] rect
A reference to a rectangle that bounds the button.

[in] strText
The text to draw.

[in] uiDTFlags
Flags that specify how to format the text. For more information, see the nFormat parameter of the CDC::DrawText method.

[in] uiState
(Reserved.)

Remarks

Override this method to use your own code to draw the button text.

Called by the framework to draw the background of the button text.

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

Parameters

[in] pDC
A pointer to a device context.

[in] rectClient
A reference to a rectangle that bounds the button.

Remarks

Override this method to use your own code to draw the background of a button.

Retrieves the font that is associated with the specified device context.

virtual CFont* SelectFont(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Return Value

Override this method to use your own code to retrieve the font.

Remarks

Sets a button to auto-repeat mode.

void SetAutorepeatMode(int nTimeDelay=500);

Parameters

[in] nTimeDelay
A nonnegative number that specifies the interval between messages that are sent to the parent window. The interval is measured in milliseconds and its default value is 500 milliseconds. Specify zero to disable auto-repeat message mode.

Remarks

This method causes the button to constantly send WM_COMMAND messages to the parent window until the button is released, or the nTimeDelay parameter is set to zero.

Sets the image for a checked button.

void SetCheckedImage(
    HICON hIcon,  
    BOOL bAutoDestroy=TRUE,  
    HICON hIconHot=NULL,  
    HICON hIconDisabled=NULL,  
    BOOL bAlphaBlend=FALSE);

 
void SetCheckedImage(
    HBITMAP hBitmap,  
    BOOL bAutoDestroy=TRUE,  
    HBITMAP hBitmapHot=NULL,  
    BOOL bMap3dColors=TRUE,  
    HBITMAP hBitmapDisabled=NULL);

 
void SetCheckedImage(
    UINT uiBmpResId,  
    UINT uiBmpHotResId=0,  
    UINT uiBmpDsblResID=0);

Parameters

[in] hIcon
Handle to the icon that contains the bitmap and mask for the new image.

[in] bAutoDestroy
TRUE to specify that bitmap resources be destroyed automatically; otherwise, FALSE. The default is TRUE.

[in] hIconHot
Handle to the icon that contains the image for the selected state.

[in] hBitmap
Handle to the bitmap that contains the image for the non-selected state.

[in] hBitmapHot
Handle to the bitmap that contains the image for the selected state.

[in] bMap3dColors
Specifies a transparent color for the button background; that is, the face of the button. TRUE to use the color value RGB(192, 192, 192); FALSE to use the color value defined by AFX_GLOBAL_DATA::clrBtnFace.

[in] uiBmpResId
Resource ID for the non-selected image.

[in] uiBmpHotResId
Resource ID for the selected image.

[in] hIconDisabled
Handle to the icon for the disabled image.

[in] hBitmapDisabled
Handle to the bitmap that contains the disabled image.

[in] uiBmpDsblResID
Resource ID of the disabled bitmap.

[in] bAlphaBlend
TRUE to use only 32-bit images that use the alpha channel; FALSE, to not use only alpha channel images. The default is FALSE.

Remarks

Sets the background color for the button text.

void SetFaceColor(
    COLORREF crFace,  
    BOOL bRedraw=TRUE);

Parameters

[in] crFace
An RGB color value.

[in] bRedraw
TRUE to redraw the screen immediately; otherwise, FALSE.

Remarks

Use this method to define a new fill color for the button background (face). Note that the background is not filled when the CMFCButton::m_bTransparent member variable is TRUE.

Sets the image for a button.

void SetImage(
    HICON hIcon,  
    BOOL bAutoDestroy=TRUE,  
    HICON hIconHot=NULL,  
    HICON hIconDisabled=NULL,  
    BOOL bAlphaBlend=FALSE);

 
void SetImage(
    HBITMAP hBitmap,  
    BOOL bAutoDestroy=TRUE,  
    HBITMAP hBitmapHot=NULL,  
    BOOL bMap3dColors=TRUE,  
    HBITMAP hBitmapDisabled=NULL);

 
void SetImage(
    UINT uiBmpResId,  
    UINT uiBmpHotResId=0,  
    UINT uiBmpDsblResID=0);

Parameters

[in] hIcon
Handle to the icon that contains the bitmap and mask for the new image.

[in] bAutoDestroy
TRUE to specify that bitmap resources be destroyed automatically; otherwise, FALSE. The default is TRUE.

[in] hIconHot
Handle to the icon that contains the image for the selected state.

[in] hBitmap
Handle to the bitmap that contains the image for the non-selected state.

[in] hBitmapHot
Handle to the bitmap that contains the image for the selected state.

[in] uiBmpResId
Resource ID for the non-selected image.

[in] uiBmpHotResId
Resource ID for the selected image.

[in] bMap3dColors
Specifies a transparent color for the button background; that is, the face of the button. TRUE to use the color value RGB(192, 192, 192); FALSE to use the color value defined by AFX_GLOBAL_DATA::clrBtnFace.

[in] hIconDisabled
Handle to the icon for the disabled image.

[in] hBitmapDisabled
Handle to the bitmap that contains the disabled image.

[in] uiBmpDsblResID
Resource ID of the disabled bitmap.

[in] bAlphaBlend
TRUE to use only 32-bit images that use the alpha channel; FALSE, to not use only alpha channel images. The default is FALSE.

Remarks

Example

The following example demonstrates how to use various versions of the SetImage method in the CMFCButton class. The example is part of the New Controls sample.

	CMFCButton m_Button;

	// int m_iImage
	// IDB_BTN1_32, IDB_BTN1_HOT_32, IDB_BTN1, IDB_BTN1_HOT are int macros that are #define.
	if (m_iImage == 1) 
	{
		m_Button.SetImage((HBITMAP) NULL);
	}
	else
	{
		m_Button.SetImage(IDB_BTN1_32, IDB_BTN1_HOT_32);
	}

Sets the cursor image.

void SetMouseCursor(HCURSOR hcursor);

Parameters

[in] hcursor
The handle of a cursor.

Remarks

Use this method to associate a cursor image, such as the hand cursor, with the button. The cursor is loaded from the application resources.

Example

The following example demonstrates how to use the SetMouseCursor method in the CMFCButton class. The example is part of the code in the New Controls sample.

	CMFCButton m_Button;

// int m_iCursor
void CPage1::OnSetCursor()
{
	UpdateData();

	switch (m_iCursor)
	{
	case 0:
		m_Button.SetMouseCursor(NULL);
		break;

	case 1:
		m_Button.SetMouseCursorHand();
		break;

	case 2:
		m_Button.SetMouseCursor(AfxGetApp()->LoadCursor(IDC_CURSOR));
		break;
	}
}

Sets the cursor to the image of a hand.

void SetMouseCursorHand();

Remarks

Use this method to associate the cursor image of a hand with the button. The cursor is loaded from the application resources.

Uses a CMenuImages object to set the button image.

void SetStdImage(
    CMenuImages::IMAGES_IDS id,  
    CMenuImages::IMAGE_STATE state=CMenuImages::ImageBlack,  
    CMenuImages::IMAGES_IDS idDisabled=(CMenuImages::IMAGES_IDS)0);

Parameters

[in] id
One of the button image identifiers that is defined in the CMenuImage::IMAGES_IDS enumeration. The image values specify images such as arrows, pins, and radio buttons.

[in] state
One of the button image state identifiers that is defined in the CMenuImages::IMAGE_STATE enumeration. The image states specify button colors such as black, gray, light gray, white, and dark gray. The default value is CMenuImages::ImageBlack.

[in] idDisabled
One of the button image identifiers that is defined in the CMenuImage::IMAGES_IDS enumeration. The image indicates that the button is disabled. The default value is the first button image ( CMenuImages::IdArrowDown).

Remarks

Sets the color of the button text for a button that is not selected.

void SetTextColor(COLORREF clrText);

Parameters

[in] clrText
An RGB color value.

Remarks

Sets the color of the button text for a button that is selected.

void SetTextHotColor(COLORREF clrTextHot);

Parameters

[in] clrTextHot
An RGB color value.

Remarks

Associates a tooltip with a button.

void SetTooltip(LPCTSTR lpszToolTipText);

Parameters

[in] lpszToolTipText
Pointer to the text for the tooltip. Specify NULL to disable the tooltip.

Remarks

Resizes a button to contain its button text and image.

virtual CSize SizeToContent(BOOL bCalcOnly=FALSE);

Parameters

[in] bCalcOnly
TRUE to calculate, but not change, the new size of the button; FALSE to change the size of the button. The default is FALSE.

Return Value

A CSize object that contains the new size of the button.

Remarks

By default, this method calculates a new size that includes a horizontal margin of 10 pixels and a vertical margin of 5 pixels.

Hierarchy Chart
Classes
CMFCLinkCtrl Class
CMFCColorButton Class
CMFCMenuButton Class

Show: