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
| Name | Description |
|---|---|
CMFCButton::CMFCButton |
Default constructor. |
CMFCButton::~CMFCButton |
Destructor. |
| 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. |
| 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. |
| Name | Description |
|---|---|
CMFCButton::m_nAlignStyle |
Specifies the alignment of the button text. |
CMFCButton::m_bDontUseWinXPTheme |
Specifies whether to use Windows XP themes. |
CMFCButton::m_bDrawFocus |
Indicates whether to draw a focus rectangle around a button. |
CMFCButton::m_nFlatStyle |
Specifies the style of the button, such as borderless, flat, semi-flat, or 3D. |
CMFCButton::m_bGrayDisabled |
When TRUE, enables a disabled button to be drawn as grayed-out. |
CMFCButton::m_bHighlightChecked |
Indicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it. |
CMFCButton::m_bResponseOnButtonDown |
Indicates whether to respond to button down events. |
CMFCButton::m_bRightImage |
Indicates whether to display an image on the right side of the button. |
CMFCButton::m_bTopImage |
Indicates whether the image is on top of the button. |
CMFCButton::m_bTransparent |
Indicates whether the button is transparent. |
CMFCButton::m_bWasDblClk |
Indicates whether the last click event was a double-click. |
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!"));
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);
bOn
[in] TRUE to display all of the text; FALSE to display truncated text.
Specifies whether the button text font is the same as the application menu font.
void EnableMenuFont(
BOOL bOn=TRUE,
BOOL bRedraw=TRUE);
bOn
[in] TRUE to use the application menu font as the button text font; FALSE to use the system font. The default is TRUE.
bRedraw
[in] TRUE to immediately redraw the screen; otherwise, FALSE. The default is TRUE.
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);
bEnable
[in] TRUE to use the current Windows theme to draw button borders; FALSE to not use the Windows theme. The default is TRUE.
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();
A reference to the underlying tooltip control.
Indicates whether a check box or radio button is an automatic button.
BOOL IsAutoCheck() const;
TRUE if the button has style BS_AUTOCHECKBOX or BS_AUTORADIOBUTTON; otherwise, FALSE.
Indicates whether a button is set to auto-repeat mode.
BOOL IsAutorepeatCommandMode() const;
TRUE if the button is set to auto-repeat mode; otherwise, FALSE.
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;
TRUE if the button has either BS_CHECKBOX or BS_AUTOCHECKBOX style; otherwise, FALSE.
Indicates whether the current button is checked.
BOOL IsChecked() const;
TRUE if the current button is checked; otherwise, FALSE.
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;
TRUE if the button is highlighted; otherwise, FALSE.
A button becomes highlighted when the mouse hovers over the button.
Indicates whether a button is pushed and highlighted.
BOOL IsPressed() const;
TRUE if the button is pressed; otherwise, FALSE.
Indicates whether a button is pushed.
BOOL IsPushed() const;
TRUE if the button is pushed; otherwise, FALSE.
Indicates whether a button is a radio button.
BOOL IsRadioButton() const;
TRUE if the button style is BS_RADIOBUTTON or BS_AUTORADIOBUTTON; otherwise, FALSE.
Indicates whether the style of the button border corresponds to the current Windows theme.
static BOOL IsWindowsThemingEnabled();
TRUE if the style of the button border corresponds to the current Windows theme; otherwise, FALSE.
Specifies whether to use Windows XP themes when drawing the button.
BOOL m_bDontUseWinXPTheme;
Indicates whether to draw a focus rectangle around a button.
BOOL m_bDrawFocus;
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.
When TRUE, enables a disabled button to be drawn as grayed-out.
BOOL m_bGrayDisabled;
Indicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it.
BOOL m_bHighlightChecked;
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 respond to button down events.
BOOL m_bResponseOnButtonDown;
Indicates whether to display an image on the right side of the button.
BOOL m_bRightImage;
Indicates whether the image is on top of the button.
BOOL m_bTopImage;
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;
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;
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.
Indicates whether the last click event was a double-click.
BOOL m_bWasDblClk;
Specifies the style of the button, such as borderless, flat, semi-flat, or 3D.
FlatStyle m_nFlatStyle;
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.
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);
pDC
[in] A pointer to a device context.
rect
[in] A reference to a rectangle that bounds the button.
uiState
[in] The current button state. For more information, see the itemState member of the DRAWITEMSTRUCT Structure topic.
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);
pDC
[in] A pointer to a device context.
rectClient
[in] A reference to a rectangle that bounds the button.
uiState
[in] The current button state. For more information, see the itemState member of the DRAWITEMSTRUCT Structure topic.
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);
pDC
[in] A pointer to a device context.
rectClient
[in] A reference to a rectangle that bounds the button.
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);
pDC
[in] A pointer to a device context.
rect
[in] A reference to a rectangle that bounds the button.
strText
[in] The text to draw.
uiDTFlags
[in] Flags that specify how to format the text. For more information, see the nFormat parameter of the CDC::DrawText method.
uiState
[in] Reserved.
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);
pDC
[in] A pointer to a device context.
rectClient
[in] A reference to a rectangle that bounds the button.
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);
pDC
[in] A pointer to a device context.
Override this method to use your own code to retrieve the font.
Sets a button to auto-repeat mode.
void SetAutorepeatMode(int nTimeDelay=500);
nTimeDelay
[in] 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.
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);
hIcon
[in] Handle to the icon that contains the bitmap and mask for the new image.
bAutoDestroy
[in] TRUE to specify that bitmap resources be destroyed automatically; otherwise, FALSE. The default is TRUE.
hIconHot
[in] Handle to the icon that contains the image for the selected state.
hBitmap
[in] Handle to the bitmap that contains the image for the non-selected state.
hBitmapHot
[in] Handle to the bitmap that contains the image for the selected state.
bMap3dColors
[in] 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.
uiBmpResId
[in] Resource ID for the non-selected image.
uiBmpHotResId
[in] Resource ID for the selected image.
hIconDisabled
[in] Handle to the icon for the disabled image.
hBitmapDisabled
[in] Handle to the bitmap that contains the disabled image.
uiBmpDsblResID
[in] Resource ID of the disabled bitmap.
bAlphaBlend
[in] TRUE to use only 32-bit images that use the alpha channel; FALSE, to not use only alpha channel images. The default is FALSE.
Sets the background color for the button text.
void SetFaceColor(
COLORREF crFace,
BOOL bRedraw=TRUE);
crFace
[in] An RGB color value.
bRedraw
[in] TRUE to redraw the screen immediately; otherwise, FALSE.
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);
hIcon
[in] Handle to the icon that contains the bitmap and mask for the new image.
bAutoDestroy
[in] TRUE to specify that bitmap resources be destroyed automatically; otherwise, FALSE. The default is TRUE.
hIconHot
[in] Handle to the icon that contains the image for the selected state.
hBitmap
[in] Handle to the bitmap that contains the image for the non-selected state.
hBitmapHot
[in] Handle to the bitmap that contains the image for the selected state.
uiBmpResId
[in] Resource ID for the non-selected image.
uiBmpHotResId
[in] Resource ID for the selected image.
bMap3dColors
[in] 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.
hIconDisabled
[in] Handle to the icon for the disabled image.
hBitmapDisabled
[in] Handle to the bitmap that contains the disabled image.
uiBmpDsblResID
[in] Resource ID of the disabled bitmap.
bAlphaBlend
[in] TRUE to use only 32-bit images that use the alpha channel; FALSE, to not use only alpha channel images. The default is FALSE.
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);
hcursor
[in] The handle of a cursor.
Use this method to associate a cursor image, such as the hand cursor, with the button. The cursor is loaded from the application resources.
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();
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);
id
[in] 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.
state
[in] 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.
idDisabled
[in] 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).
Sets the color of the button text for a button that is not selected.
void SetTextColor(COLORREF clrText);
clrText
[in] An RGB color value.
Sets the color of the button text for a button that is selected.
void SetTextHotColor(COLORREF clrTextHot);
clrTextHot
[in] An RGB color value.
Associates a tooltip with a button.
void SetTooltip(LPCTSTR lpszToolTipText);
lpszToolTipText
[in] Pointer to the text for the tooltip. Specify NULL to disable the tooltip.
Resizes a button to contain its button text and image.
virtual CSize SizeToContent(BOOL bCalcOnly=FALSE);
bCalcOnly
[in] TRUE to calculate, but not change, the new size of the button; FALSE to change the size of the button. The default is FALSE.
A CSize object that contains the new size of the button.
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