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.
Syntax
class CMFCButton : public CButton
Members
Public Constructors
Name | Description |
---|---|
CMFCButton::CMFCButton |
Default constructor. |
CMFCButton::~CMFCButton |
Destructor. |
Public Methods
Name | Description |
---|---|
CMFCButton::CleanUp | Resets internal variables and frees allocated resources such as images, bitmaps, and icons. |
CMFCButton::CreateObject |
Used by the framework to create a dynamic instance of this class type. |
CMFCButton::DrawItem |
Called by the framework when a visual aspect of an owner-drawn button has changed. (Overrides CButton::DrawItem.) |
CMFCButton::EnableFullTextTooltip | 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. |
CMFCButton::EnableMenuFont | Specifies whether the button text font is the same as the application menu font. |
CMFCButton::EnableWindowsTheming | Specifies whether the style of the button border corresponds to the current Windows theme. |
CMFCButton::GetThisClass |
Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type. |
CMFCButton::GetToolTipCtrl | Returns a reference to the underlying tooltip control. |
CMFCButton::IsAutoCheck | Indicates whether a check box or radio button is an automatic button. |
CMFCButton::IsAutorepeatCommandMode | Indicates whether a button is set to auto-repeat mode. |
CMFCButton::IsCheckBox | Indicates whether a button is a check box button. |
CMFCButton::IsChecked | Indicates whether the current button is checked. |
CMFCButton::IsHighlighted | Indicates whether a button is highlighted. |
CMFCButton::IsPressed | Indicates whether a button is pushed and highlighted. |
CMFCButton::IsPushed | Indicates whether a button is pushed. |
CMFCButton::IsRadioButton | Indicates whether a button is a radio button. |
CMFCButton::IsWindowsThemingEnabled | Indicates whether the style of the button border corresponds to the current Windows theme. |
CMFCButton::OnDrawParentBackground |
Draws the background of a button's parent in the specified area. (Overrides AFX_GLOBAL_DATA::DrawParentBackground |
CMFCButton::PreTranslateMessage |
Translates window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. (Overrides CWnd::PreTranslateMessage.) |
CMFCButton::SetAutorepeatMode | Sets a button to auto-repeat mode. |
CMFCButton::SetCheckedImage | Sets the image for a checked button. |
CMFCButton::SetFaceColor | Sets the background color for the button text. |
CMFCButton::SetImage | Sets the image for a button. |
CMFCButton::SetMouseCursor | Sets the cursor image. |
CMFCButton::SetMouseCursorHand | Sets the cursor to the image of a hand. |
CMFCButton::SetStdImage | Uses a CMenuImages object to set the button image. |
CMFCButton::SetTextColor | Sets the color of the button text for a button that is not selected. |
CMFCButton::SetTextHotColor | Sets the color of the button text for a button that is selected. |
CMFCButton::SetTooltip | Associates a tooltip with a button. |
CMFCButton::SizeToContent | Resizes a button to contain its button text and image. |
Protected Methods
Name | Description |
---|---|
CMFCButton::OnDraw | Called by the framework to draw a button. |
CMFCButton::OnDrawBorder | Called by the framework to draw the border of a button. |
CMFCButton::OnDrawFocusRect | Called by the framework to draw the focus rectangle for a button. |
CMFCButton::OnDrawText | Called by the framework to draw the button text. |
CMFCButton::OnFillBackground | Called by the framework to draw the background of the button text. |
CMFCButton::SelectFont | Retrieves the font that is associated with the specified device context. |
Data Members
Name | Description |
---|---|
CMFCButton::m_bDrawFocus | Indicates whether to draw a focus rectangle around a button. |
CMFCButton::m_bHighlightChecked | Indicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it. |
CMFCButton::m_bRightImage | Indicates whether to display an image on the right side of the button. |
CMFCButton::m_bTransparent | Indicates whether the button is transparent. |
CMFCButton::m_nAlignStyle | Specifies the alignment of the button text. |
CMFCButton::m_nFlatStyle | Specifies the style of the button, such as borderless, flat, semi-flat, or 3D. |
Remarks
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.
Example
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!"));
Inheritance Hierarchy
Requirements
Header: afxbutton.h
CMFCButton::CleanUp
Resets internal variables and frees allocated resources such as images, bitmaps, and icons.
virtual void CleanUp();
CMFCButton::EnableFullTextTooltip
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
CMFCButton::EnableMenuFont
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.
CMFCButton::EnableWindowsTheming
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.
CMFCButton::GetToolTipCtrl
Returns a reference to the underlying tooltip control.
CToolTipCtrl& GetToolTipCtrl();
Return Value
A reference to the underlying tooltip control.
Remarks
CMFCButton::IsAutoCheck
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
CMFCButton::IsAutorepeatCommandMode
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.
CMFCButton::IsCheckBox
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
CMFCButton::IsChecked
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.
CMFCButton::IsHighlighted
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.
CMFCButton::IsPressed
Indicates whether a button is pushed and highlighted.
BOOL IsPressed() const;
Return Value
TRUE if the button is pressed; otherwise, FALSE.
Remarks
CMFCButton::IsPushed
Indicates whether a button is pushed.
BOOL IsPushed() const;
Return Value
TRUE if the button is pushed; otherwise, FALSE.
Remarks
CMFCButton::IsRadioButton
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
CMFCButton::IsWindowsThemingEnabled
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
.
CMFCButton::m_bDrawFocus
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
.
CMFCButton::m_bHighlightChecked
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.
CMFCButton::m_bRightImage
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.
CMFCButton::m_bTransparent
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
.
CMFCButton::m_nAlignStyle
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:
Value | Description |
---|---|
ALIGN_CENTER | (Default) Aligns the button text to the center of the button. |
ALIGN_LEFT | Aligns the button text to the left side of the button. |
ALIGN_RIGHT | Aligns the button text to the right side of the button. |
The CMFCButton
constructor initializes this member to ALIGN_CENTER.
CMFCButton::m_nFlatStyle
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.
Value | Description |
---|---|
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_FLAT | When 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_SEMIFLAT | The button appears to have low, three-dimensional sides. When the button is clicked, the button appears to be pressed into a deep indentation. |
BUTTONSTYLE_NOBORDERS | The 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;
}
CMFCButton::OnDraw
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.
CMFCButton::OnDrawBorder
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.
CMFCButton::OnDrawFocusRect
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.
CMFCButton::OnDrawText
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.
CMFCButton::OnFillBackground
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.
CMFCButton::SelectFont
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
CMFCButton::SetAutorepeatMode
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.
CMFCButton::SetCheckedImage
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
CMFCButton::SetFaceColor
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
.
CMFCButton::SetImage
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);
}
CMFCButton::SetMouseCursor
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;
}
}
CMFCButton::SetMouseCursorHand
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.
CMFCButton::SetStdImage
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
CMFCButton::SetTextColor
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
CMFCButton::SetTextHotColor
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
CMFCButton::SetTooltip
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
CMFCButton::SizeToContent
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.
See Also
Hierarchy Chart
Classes
CMFCLinkCtrl Class
CMFCColorButton Class
CMFCMenuButton Class