# 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