Compartir a través de

CSplitButton Class

  • Artículo

 

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

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.

Dialog with a splitbutton and pager control.

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

Parameter Description
[in] dwStyle A bitwise combination (OR) of styles to be applied to the control. For more information, see Button Styles.
[in] rect A reference to a RECT structure that contains the position and size of the control.
[in] pParentWnd A non-null pointer to a CWnd object that is the parent window of the control.
[in] nID 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

Parameter Description
[in] nMenuId The resource ID of the menu bar.
[in] nSubMenuId The resource ID of a submenu.
[in] pMenu 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

Parameter Description
[in] pNMHDR Pointer 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()

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

Parameter Description
[in] nMenuId The resource ID of the menu bar.
[in] nSubMenuId The resource ID of a submenu.
[in] pMenu 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.

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

See Also

CSplitButton Class
Hierarchy Chart
CButton Class