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.

Syntax

class CSplitButton : public CButton  

Members

Public Constructors

Public Methods

Protected Methods

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

CObject

CCmdTarget

CWnd

CButton

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

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

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

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

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

See Also

CSplitButton Class
Hierarchy Chart
CButton Class