CSplitButton Class
The CSplitButton class represents a split button control. The split button control performs a default behavior when a user clicks the main part of the button, and displays a drop-down menu when a user clicks the drop-down arrow of the button.
Syntax
class CSplitButton : public CButton
Members
Public Constructors
| Name | Description |
|---|---|
| CSplitButton::CSplitButton | Constructs a CSplitButton object. |
Public Methods
| Name | Description |
|---|---|
| CSplitButton::Create | Creates a split button control with specified styles and attaches it to the current CSplitButton object. |
| CSplitButton::SetDropDownMenu | Sets the drop-down menu that is displayed when a user clicks the drop-down arrow of the current split button control. |
Protected Methods
| Name | Description |
|---|---|
| CSplitButton::OnDropDown | Handles the BCN_DROPDOWN notification that the system sends when a user clicks the drop-down arrow of the current split button control. |
Remarks
The CSplitButton class is derived from the CButton class. The split button control is a button control whose style is BS_SPLITBUTTON. It displays a custom menu when a user clicks the drop-down arrow. For more information, see the BS_SPLITBUTTON and BS_DEFSPLITBUTTON styles in Button Styles.
The following figure depicts a dialog box that contains a pager control and a (1) split button control. The (2) drop-down arrow has already been clicked and the (3) submenu is displayed.
Inheritance Hierarchy
CSplitButton
Requirements
Header: afxcmn.h
This class is supported in Windows Vista and later.
Additional requirements for this class are described in Build Requirements for Windows Vista Common Controls.
CSplitButton::Create
Creates a split button control with specified styles and attaches it to the current CSplitButton object.
virtual BOOL Create(
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
Parameters
dwStyle
[in] A bitwise combination (OR) of styles to be applied to the control. For more information, see Button Styles.
rect
[in] A reference to a RECT structure that contains the position and size of the control.
pParentWnd
[in] A non-null pointer to a CWnd object that is the parent window of the control.
nID
[in] The ID of the control.
Return Value
TRUE if this method is successful; otherwise, FALSE.
CSplitButton::CSplitButton
Constructs a CSplitButton object. The constructor's parameters specify a submenu that is displayed when a user clicks the drop-down arrow of the split button control.
CSplitButton();
CSplitButton(
UINT nMenuId,
UINT nSubMenuId)
CSplitButton(CMenu* pMenu)
Parameters
nMenuId
[in] The resource ID of the menu bar.
nSubMenuId
[in] The resource ID of a submenu.
pMenu
[in] A pointer to a CMenu object that specifies a submenu. The CSplitButton object deletes the CMenu object and its associated HMENU when the CSplitButton object goes out of scope.
Remarks
Use the CSplitButton::Create method to create a split button control and attach it to the CSplitButton object.
CSplitButton::OnDropDown
Handles the BCN_DROPDOWN notification that the system sends when a user clicks the drop-down arrow of the current split button control.
afx_msg void OnDropDown(
NMHDR* pNMHDR,
LRESULT* pResult);
Parameters
pNMHDR
[in] Pointer to an NMHDR structure that contains information about the BCN_DROPDOWN notification.
pResult
[out] (Not used; no value is returned.) Return value of the BCN_DROPDOWN notification.
Remarks
When the user clicks the drop-down arrow on a split button control, system sends a BCN_DROPDOWN notification message, which the OnDropDown method handles. However, the CSplitButton object does not forward the BCN_DROPDOWN notification to the control that contains the split button control. Consequently, the containing control cannot support a custom action in response to the notification.
To implement a custom action that the containing control supports, use a CButton object with a style of BS_SPLITBUTTON instead of a CSplitButton object. Then implement a handler for the BCN_DROPDOWN notification in the CButton object. For more information, see Button Styles.
To implement a custom action that the split button control itself supports, use message reflection. Derive your own class from the CSplitButton class and name it, for example, CMySplitButton. Then add the following message map to your application to handle the BCN_DROPDOWN notification:
BEGIN_MESSAGE_MAP(CMySplitButton,
CSplitButton)
ON_NOTIFY_REFLECT(BCN_DROPDOWN, &CMySplitButton::OnDropDown)
END_MESSAGE_MAP()
CSplitButton::SetDropDownMenu
Sets the drop-down menu that is displayed when a user clicks the drop-down arrow of the current split button control.
void SetDropDownMenu(
UINT nMenuId,
UINT nSubMenuId);
void SetDropDownMenu(CMenu* pMenu);
Parameters
nMenuId
[in] The resource ID of the menu bar.
nSubMenuId
[in] The resource ID of a submenu.
pMenu
[in] Pointer to a CMenu object that specifies a submenu. The CSplitButton object deletes the CMenu object and its associated HMENU when the CSplitButton object goes out of scope.
Remarks
The nMenuId parameter identifies a menu bar, which is a horizontal list of menu bar items. The nSubMenuId parameter is a zero-based index number that identifies a submenu, which is the drop-down list of menu items associated with each menu bar item. For example, a typical application has a menu that contains the menu bar items, "File," "Edit," and "Help." The "File" menu bar item has a submenu that contains the menu items, "Open," "Close" and "Exit." When the drop-down arrow of the split-button control is clicked, the control displays the specified submenu, not the menu bar.
The following figure depicts a dialog box that contains a pager control and a (1) split button control. The (2) drop-down arrow has already been clicked and the (3) submenu is displayed.
Example
The first statement in the following code example demonstrates the CSplitButton::SetDropDownMenu method. We created the menu with the Visual Studio resource editor, which automatically named the menu bar ID, IDR_MENU1. The nSubMenuId parameter, which is zero, refers to the only submenu of the menu bar.
// Initialize the dropdown menu of the splitbutton control.
m_splitButton.SetDropDownMenu(IDR_MENU1, 0);
// Create the pager control.
BOOL nRet;
CRect rect;
GetClientRect(&rect);
nRet = m_pager.Create(
(WS_VISIBLE | WS_CHILD | PGS_HORZ),
CRect(rect.Width() / 4, 5, (rect.Width() * 3) / 4, 55),
this,
IDC_PAGER1);
m_pager.GetClientRect(&rect);
nRet = m_button.Create(
_T("This is a very, very long button. 012345678901234567890"),
(WS_VISIBLE | WS_CHILD), // Do not use CCS_NORESIZE.
CRect(0, 0, rect.Width(), 30),
&m_pager, IDC_BUTTON1);
m_pager.SetChild(m_button.m_hWnd);
m_pager.SetButtonSize(20);
m_pager.SetBorder(1);