BCX_SPLITBUTTON

Creates a Windows Split Button control. A split button is a button divided into two parts: a main button that performs a default action, and a dropdown arrow that displays a menu of additional options. When an option is selected from the dropdown menu, the button's caption automatically updates to reflect the selection.

Syntax

hControl = BCX_SPLITBUTTON(Caption$, hParent, CtlID, X, Y, W, H [, Style [, ExStyle]])

Parameters

Parameter	Description
`Caption$`	Initial text displayed on the button face.
`hParent`	Handle to the parent window (typically a form).
`CtlID`	Control identifier. This should match the ID of the default menu item.
`X`	Horizontal position of the control.
`Y`	Vertical position of the control.
`W`	Width of the control. Ensure this is wide enough to display the longest menu item.
`H`	Height of the control.
`Style`	(Optional) Window style flags. Default: `WS_CHILD \| WS_VISIBLE \| BS_SPLITBUTTON \| WS_TABSTOP \| BS_TEXT \| BS_VCENTER`
`ExStyle`	(Optional) Extended window style flags. Default: 0

Return Value

Returns the handle (HWND) of the created split button control.

Related Functions

BCX_SPLITBUTTON_ADDITEM

Adds a single menu item to the split button's dropdown menu.

BCX_SPLITBUTTON_ADDITEM(hSplitButton, Label$, ItemID)

Parameter	Description
`hSplitButton`	Handle to the split button control.
`Label$`	Text to display for this menu item.
`ItemID`	Unique identifier for this menu item. This ID is sent via WM_COMMAND when clicked.

BCX_SPLITBUTTON_ADDSEPARATOR

Adds a horizontal separator line to the split button's dropdown menu.

BCX_SPLITBUTTON_ADDSEPARATOR(hSplitButton)

Parameter	Description
`hSplitButton`	Handle to the split button control.

BCX_SPLITBUTTON_SETITEMS

Assigns multiple menu items at once from an array of BCX_SPLITBUTTONDATA structures.

BCX_SPLITBUTTON_SETITEMS(hSplitButton, pItems, Count)

Parameter	Description
`hSplitButton`	Handle to the split button control.
`pItems`	Pointer to an array of `BCX_SPLITBUTTONDATA` structures.
`Count`	Number of items in the array.

BCX_SPLITBUTTONDATA Structure

TYPE BCX_SPLITBUTTONDATA
    szLabel AS ASCIIZ * 256    ' Menu item text
    nID     AS INT             ' Menu item identifier
END TYPE

Remarks

Automatic Caption Update: When the user selects an item from the dropdown menu, the split button's caption automatically updates to display the selected item's text. You do not need to call BCX_SET_TEXT manually.

Control ID Behavior: When a menu item is selected, the control's ID changes to match the selected item's ID. This means CBCTL in your event handler will contain the ID of the currently selected/clicked item.

Button Width: Ensure the button width is sufficient to display the longest menu item text plus the dropdown arrow (approximately 48 pixels for the arrow).

Example 1: Using ADDITEM

GUI "SplitButton Demo"

ENUM
    SB_CUT
    SB_COPY
    SB_PASTE
    SB_DELETE
END ENUM

GLOBAL AS HWND Form1, hSplitButt

SUB FORMLOAD
    Form1 = BCX_FORM("SplitButton Demo", 0, 0, 300, 200)
    
    hSplitButt = BCX_SPLITBUTTON("Cut", Form1, SB_CUT, 10, 10, 100, 25)
    
    BCX_SPLITBUTTON_ADDITEM(hSplitButt, "Cut",    SB_CUT)
    BCX_SPLITBUTTON_ADDITEM(hSplitButt, "Copy",   SB_COPY)
    BCX_SPLITBUTTON_ADDITEM(hSplitButt, "Paste",  SB_PASTE)
    BCX_SPLITBUTTON_ADDSEPARATOR(hSplitButt)
    BCX_SPLITBUTTON_ADDITEM(hSplitButt, "Delete", SB_DELETE)
    
    CENTER Form1
    SHOW Form1
END SUB

BEGIN EVENTS
    SELECT CASE CBMSG
    CASE WM_COMMAND
        SELECT CASE CBCTL
        CASE SB_CUT    : MSGBOX "Cut clicked"
        CASE SB_COPY   : MSGBOX "Copy clicked"
        CASE SB_PASTE  : MSGBOX "Paste clicked"
        CASE SB_DELETE : MSGBOX "Delete clicked"
        END SELECT
    END SELECT
END EVENTS

Example 2: Using SETITEMS with Array

GUI "SplitButton Demo"

ENUM
    SB_APPLES
    SB_BANANAS
    SB_GRAPES
    SB_ORANGES
END ENUM

GLOBAL AS HWND Form1, hSplitButt

SUB FORMLOAD
    DIM AS BCX_SPLITBUTTONDATA MenuItems[4]
    
    Form1 = BCX_FORM("SplitButton Demo", 0, 0, 300, 200)
    
    hSplitButt = BCX_SPLITBUTTON("Apples", Form1, SB_APPLES, 10, 10, 100, 25)
    
    MenuItems[0].szLabel = "Apples"
    MenuItems[0].nID = SB_APPLES
    MenuItems[1].szLabel = "Bananas"
    MenuItems[1].nID = SB_BANANAS
    MenuItems[2].szLabel = "Grapes"
    MenuItems[2].nID = SB_GRAPES
    MenuItems[3].szLabel = "Oranges"
    MenuItems[3].nID = SB_ORANGES
    
    BCX_SPLITBUTTON_SETITEMS(hSplitButt, ADDRESSOF(MenuItems[0]), 4)
    
    CENTER Form1
    SHOW Form1
END SUB

BEGIN EVENTS
    SELECT CASE CBMSG
    CASE WM_COMMAND
        SELECT CASE CBCTL
        CASE SB_APPLES  : MSGBOX "Apples"
        CASE SB_BANANAS : MSGBOX "Bananas"
        CASE SB_GRAPES  : MSGBOX "Grapes"
        CASE SB_ORANGES : MSGBOX "Oranges"
        END SELECT
    END SELECT
END EVENTS

Summary

Function	Purpose
`BCX_SPLITBUTTON`	Create the split button control
`BCX_SPLITBUTTON_ADDITEM`	Add a single menu item
`BCX_SPLITBUTTON_ADDSEPARATOR`	Add a separator line
`BCX_SPLITBUTTON_SETITEMS`	Bulk assign menu items from array

See Also: BCX_BUTTON BCX_FORM ENUM