CSplitButton 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 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.

class CSplitButton : public CButton  

Public Constructors

NameDescription
CSplitButton::CSplitButtonConstructs a CSplitButton object.

Public Methods

NameDescription
CSplitButton::CreateCreates a split button control with specified styles and attaches it to the current CSplitButton object.
CSplitButton::SetDropDownMenuSets the drop-down menu that is displayed when a user clicks the drop-down arrow of the current split button control.

Protected Methods

NameDescription
CSplitButton::OnDropDownHandles the BCN_DROPDOWN notification that the system sends when a user clicks the drop-down arrow of the current split button control.

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.

Dialog with a splitbutton and pager control.

CObject

CCmdTarget

CWnd

CButton

CSplitButton

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.

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

ParameterDescription
[in] dwStyleA bitwise combination (OR) of styles to be applied to the control. For more information, see Button Styles.
[in] rectA reference to a RECT structure that contains the position and size of the control.
[in] pParentWndA non-null pointer to a CWnd object that is the parent window of the control.
[in] nIDThe ID of the control.

Return Value

true if this method is successful; otherwise, false.

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

ParameterDescription
[in] nMenuIdThe resource ID of the menu bar.
[in] nSubMenuIdThe resource ID of a submenu.
[in] pMenuA 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.

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

ParameterDescription
[in] pNMHDRPointer to an NMHDR structure that contains information about the BCN_DROPDOWN notification.
[out] pResult(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()  

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

ParameterDescription
[in] nMenuIdThe resource ID of the menu bar.
[in] nSubMenuIdThe resource ID of a submenu.
[in] pMenuPointer 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.

Dialog with a splitbutton and pager control.

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 );

CSplitButton Class
Hierarchy Chart
CButton Class

Show: