第 134 章 Checkbox 复选框

概念

Checkbox 用于多项选择场景：
• 点击切换选中/未选中
• 指示器（方框/勾选图标）可自定义 Surface
• 支持内置图集（UseBuiltinAtlas）快速使用默认图标
• 变化回调通知业务逻辑

API 速查

函数	说明
`int xuiCheckBoxCreate(xui_context pCtx, xui_widget* ppW, const xui_checkbox_desc_t* pDesc)`	创建复选框
`int xuiCheckBoxSetChange(xui_widget pW, xui_checkbox_change_proc onChange, void* pUser)`	变化回调
`int xuiCheckBoxSetText(xui_widget pW, const char* sText)`	设置文本
`int xuiCheckBoxSetChecked(xui_widget pW, int bChecked)`	设置选中
`int xuiCheckBoxGetChecked(xui_widget pW)`	获取选中
`int xuiCheckBoxSetIndicatorSize(xui_widget pW, float fSize)`	指示器大小
`int xuiCheckBoxSetGap(xui_widget pW, float fGap)`	图标与文字间距
`int xuiCheckBoxSetColors(xui_widget pW, uint32_t iAccent, uint32_t iBorder, uint32_t iHoverBorder, uint32_t iFocus)`	颜色
`int xuiCheckBoxSetIndicatorSurface(xui_widget pW, ...)`	自定义图标
`int xuiCheckBoxUseBuiltinAtlas(xui_widget pW, int bEnable)`	内置图集

编译本章示例

gcc -O2 -I. -o ch134.exe ch134_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch134.exe

示例：设置项复选框

static void OnVsyncChange(xui_widget pW,
    int bChecked, void* pUser)
{
    printf("VSync: %s\n", bChecked ? "ON" : "OFF");
}

xui_checkbox_desc_t desc = { 0 };
desc.sText = "启用垂直同步";
desc.bChecked = 1;

xui_widget pChk;
xuiCheckBoxCreate(pCtx, &pChk, &desc);
xuiCheckBoxSetChange(pChk, OnVsyncChange, NULL);
xuiCheckBoxUseBuiltinAtlas(pChk, 1);
xuiCheckBoxSetIndicatorSize(pChk, 18.0f);
xuiCheckBoxSetGap(pChk, 8.0f);

// 强调色
xuiCheckBoxSetColors(pChk,
    0xFF3B82F6, 0xFF6B7280,
    0xFF9CA3AF, 0x403B82F6);

xuiWidgetAddChild(pSettingsPanel, pChk);

完整代码

将以下代码保存为 ch134_main.c，编译后运行即可看到复选框交互：

#include "xge.h"
#include "xui.h"
#include <stdio.h>

static xui_context g_pCtx;

static void OnVsyncChange(xui_widget pW,
    int bChecked, void* pUser) {
    (void)pW; (void)pUser;
    printf("VSync: %s\n",
        bChecked ? "ON" : "OFF");
}

static int onFrame(void* pUser) {
    (void)pUser;
    xgeClear(0x081114FF);
    float mx, my;
    xgeMouseGet(&mx, &my);
    xuiInputPointerMove(g_pCtx, mx, my, 0);
    if (xgeMouseDown(XGE_MOUSE_LEFT))
        xuiInputPointerDown(g_pCtx, mx, my, 0, 1);
    if (!xgeMouseDown(XGE_MOUSE_LEFT) /* 释放边沿建议改用事件 */)
        xuiInputPointerUp(g_pCtx, mx, my, 0, 0);
    xuiUpdate(g_pCtx, xgeGetDelta());
    xuiLayout(g_pCtx);
    xuiRender(g_pCtx, NULL, NULL, 0);
    return XGE_OK;
}

int main(void) {
    xge_desc_t d = {0};
    d.iWidth  = 800;
    d.iHeight = 600;
    d.sTitle  = "ch134 - CheckBox";
    d.iFlags  = XGE_INIT_VSYNC;
    xgeInit(&d);

    xuiCreate(&g_pCtx);
    extern const xui_proxy_t tXgeProxy;
    xui_proxy_t tXgeProxy = xuiProxyXge();
xuiSetProxy(g_pCtx, &tXgeProxy);
    xuiSetViewportSize(g_pCtx, 800, 600);

    // 创建复选框
    xui_checkbox_desc_t desc = { 0 };
    desc.sText = "Enable VSync";
    desc.bChecked = 1;
    xui_widget pChk;
    xuiCheckBoxCreate(g_pCtx, &pChk, &desc);
    xuiCheckBoxSetChange(pChk,
        OnVsyncChange, NULL);
    xuiCheckBoxUseBuiltinAtlas(pChk, 1);
    xuiCheckBoxSetIndicatorSize(pChk, 18.0f);
    xuiWidgetSetRect(pChk,
        (xui_rect_t){ 300, 280, 200, 30 });

    xgeRun(onFrame, NULL);

    xuiDestroy(g_pCtx);
    xgeUnit();
    return 0;
}

代码讲解

xuiCheckBoxCreate：创建复选框，desc 中设置初始文本和选中状态。
xuiCheckBoxSetChange：注册变化回调，用户切换时触发。
xuiCheckBoxUseBuiltinAtlas：使用内置勾选图标，无需提供 Surface。
SetChecked 不触发回调：编程设置不会触发 onChange，避免循环。

要点与陷阱

回调参数：onChange 第二参数为新的选中状态。
BuiltinAtlas：启用后无需提供 Surface，使用内置勾选图标。
Accent：选中时指示器填充色。
编程设置：SetChecked 不触发 onChange 回调（避免循环）。

进阶练习

全选/反选：父级 Checkbox 控制子级列表。
自定义图标：用 Surface 替换为圆形/星形指示器。

← 第 133 章第 135 章：Radio 单选按钮 →