跳到主要内容

复选框 Checkbox

复选框就是那个小方框，打勾表示"是"，空白表示"否"。它最适合用来做开关选项，比如"显示网格"、"开启音效"、"自动保存"之类的布尔设置。

返回值 vs Checked 字段

Checkbox() 的返回值表示"这一帧是否发生了状态切换"（即用户刚刚点击了它）。而 Profile.Checked 字段表示"当前是否处于选中状态"。两者不一样，别搞混啦！

函数原型​

bool Checkbox(const HXString &Title, CheckboxProfile &Profile);

参数说明​

参数类型说明
Titleconst HXString &复选框旁边的文字标签。使用 HXStr("标签") 或 L"标签"。
ProfileCheckboxProfile &复选框的配置结构体。必须是 static 或全局变量。

返回值​

类型说明
booltrue —— 用户刚刚点击了复选框，状态发生了切换。
false —— 没有发生点击。
返回值和 Checked 的区别
  • 返回值 = true：只在用户点击的那一帧为 true，适合触发一次性动作（比如"点击后刷新界面"）。
  • Profile.Checked = true：只要复选框处于选中状态就为 true，适合读取当前设置（比如"根据这个值决定是否播放音效"）。

CheckboxProfile 结构体​

字段类型默认值说明
Checkedboolfalse当前是否选中。可以被你读取或修改。
OnFocusboolfalse是否拥有焦点。由框架自动维护。
BoxSizeint22复选框方框的边长（像素）。
FontSizeint20标签文字的字体大小。
Disabledboolfalse是否禁用。禁用后无法交互，视觉样式也会变灰。

基本用法​

读取选中状态​

static HX::CheckboxProfile cbProfile;
HX::Checkbox(HXStr("显示网格"), cbProfile);

if (cbProfile.Checked) {
    // 绘制网格...
}

检测状态切换（点击事件）​

static HX::CheckboxProfile cbProfile;
if (HX::Checkbox(HXStr("开启音效"), cbProfile)) {
    // 用户刚刚切换了这个选项
    if (cbProfile.Checked) {
        playSound(HXStr("click.wav"));
    }
}

禁用状态​

static HX::CheckboxProfile cbProfile;
cbProfile.Disabled = true;  // 用户点不了这个复选框
HX::Checkbox(HXStr("高级功能（未解锁）"), cbProfile);
生命周期警告！

CheckboxProfile 必须是 static 或全局变量。如果写成局部变量，Checked 状态每一帧都会重置为 false，复选框永远打不上勾！

在代码中修改选中状态​

有时候你需要在代码里强制改变复选框的状态（比如点击"全部重置"按钮时），直接修改 Checked 即可：

static HX::CheckboxProfile cbSound;
static HX::CheckboxProfile cbGrid;
static HX::ButtonProfile btnReset;

if (HX::Button(HXStr("恢复默认设置"), btnReset)) {
    cbSound.Checked = true;
    cbGrid.Checked = false;
}

HX::Checkbox(HXStr("音效"), cbSound);
HX::Checkbox(HXStr("网格"), cbGrid);

完整示例代码​

下面的示例展示了三个复选框，分别控制"显示网格"、"开启音效"和"高级模式"。其中"高级模式"被禁用了，还有一个"全选/取消"按钮用来批量操作。

#include <include/hex.h>
#include <include/impl/EasyX/hex_impl_easyx.h>

int main() {
    initgraph(800, 600);
    setbkcolor(WHITE);
    cleardevice();

    HX::HXInitForEasyX();
    HX::SetBuffer(GetWorkingImage());

    BeginBatchDraw();

    // ===== 必须是 static 或全局变量 =====
    static HX::WindowProfile wp;
    wp.Size = {450, 400};
    wp.Position = {175, 100};

    static HX::CheckboxProfile cbGrid;
    static HX::CheckboxProfile cbSound;
    static HX::CheckboxProfile cbAdvanced;
    cbAdvanced.Disabled = true;  // 默认禁用

    static HX::ButtonProfile btnAll;
    static HX::ButtonProfile btnNone;
    static HX::ButtonProfile btnToggle;

    while (true) {
        HX::HXBegin();

        ExMessage msg;
        while (peekmessage(&msg)) {
            HX::PushMessage(HX::GetHXMessage(&msg));
        }

        HX::Window(HXStr("Checkbox 演示"), wp);

        // 三个复选框
        HX::Checkbox(HXStr("显示网格"), cbGrid);
        HX::Checkbox(HXStr("开启音效"), cbSound);
        HX::Checkbox(HXStr("高级模式（未解锁）"), cbAdvanced);

        HX::Text(HXStr("批量操作:"));

        // 全选按钮
        if (HX::Button(HXStr("全部选中"), btnAll)) {
            cbGrid.Checked = true;
            cbSound.Checked = true;
            // cbAdvanced 保持原样，因为它被禁用了
        }

        // 全不选按钮
        if (HX::Button(HXStr("全部取消"), btnNone)) {
            cbGrid.Checked = false;
            cbSound.Checked = false;
        }

        // 反选按钮
        if (HX::Button(HXStr("反选"), btnToggle)) {
            cbGrid.Checked = !cbGrid.Checked;
            cbSound.Checked = !cbSound.Checked;
        }

        // 显示当前状态
        HX::Text(HXStr("--- 当前状态 ---"));
        HX::Text(HXStr("网格: ") + (cbGrid.Checked ? HXStr("开") : HXStr("关")));
        HX::Text(HXStr("音效: ") + (cbSound.Checked ? HXStr("开") : HXStr("关")));

        HX::End();
        HX::Render();
        FlushBatchDraw();
        Sleep(16);
    }

    closegraph();
    return 0;
}
小建议

很多新手会写出这样的代码：if (HX::Checkbox(...)) { Profile.Checked = true; }。这是错的！点击之后，框架已经自动把 Checked 取反了，你不需要再手动赋值。if 分支里应该放"因为状态变了所以要做的动作"，而不是修改 Checked 本身。

运行效果​

截图占位符：请补充 $name 控件的运行效果截图。

截图占位符：请补充 Checkbox 运行效果 的运行效果截图，保存为 ./assets/Checkbox_view.png。`n