跳到主要内容

滑块 Slider

滑块（Slider）是调节数值的利器。拖拽一下，参数就变大了；往回拉，参数又变小。HiEasyX 的滑块支持 1~4 维的 float 和 int 版本，也就是说你可以用一个滑块同时控制 RGBA 四个通道，或者只控制一个音量大小。

版本命名规律
  • Slider1f = 1 维 float
  • Slider2f = 2 维 float（比如 {x, y}）
  • Slider3f = 3 维 float（比如 RGB）
  • Slider4f = 4 维 float（比如 RGBA）
  • Slider1i / Slider2i / Slider3i / Slider4i 同理，只是类型换成 int

函数原型​

// Float 版本
void Slider1f(const HXString &Title, float       &Value, SliderProfile1f &Profile);
void Slider2f(const HXString &Title, float       (&Value)[2], SliderProfile2f &Profile);
void Slider3f(const HXString &Title, float       (&Value)[3], SliderProfile3f &Profile);
void Slider4f(const HXString &Title, float       (&Value)[4], SliderProfile4f &Profile);

// Int 版本
void Slider1i(const HXString &Title, int         &Value, SliderProfile1i &Profile);
void Slider2i(const HXString &Title, int         (&Value)[2], SliderProfile2i &Profile);
void Slider3i(const HXString &Title, int         (&Value)[3], SliderProfile3i &Profile);
void Slider4i(const HXString &Title, int         (&Value)[4], SliderProfile4i &Profile);
注意

具体的数据结构名称（HXPointF、HXColorF 等）以你项目中的实际定义为准。核心概念是：多维度版本接收一个结构体指针，滑块会同时控制其中的多个分量。

参数说明​

参数类型说明
Titleconst HXString &滑块左侧的标签文字。
Value对应类型的指针被滑块控制的数值。会被直接修改。必须是持久化的变量。
ProfileSliderProfileXx &滑块的配置结构体。必须是 static 或全局变量。

返回值​

Slider 系列函数没有返回值。被修改的数值直接写回到 Value 指针指向的变量中。

SliderProfile 结构体（以 1f 为例，其他维度类似）​

字段类型默认值说明
InDragboolfalse当前是否正在拖拽滑块。由框架自动维护。
OnFocusboolfalse滑块是否拥有焦点。由框架自动维护。
InEditModeboolfalse当前是否处于"输入框编辑模式"。由框架自动维护。
MinValuefloat / int0.0f / 0滑块允许的最小值。
MaxValuefloat / int1.0f / 100滑块允许的最大值。
Widthint-1滑块轨道的宽度。-1 表示自动填充剩余空间。
Stepfloat / int0.0f / 0步进值。0 表示连续变化；否则按步长离散跳跃。
FormatCallbackstd::function<HXString(float)>nullptr自定义数值格式化回调，控制右侧显示的文字。
FontSizeint20标签文字的字体大小。
Heightint22滑块控件的高度。
关于步进 Step

如果 Step 设为 0.1f，那么滑块的值会以 0.1 为单位跳跃，适合需要精细控制但不想出现无穷小数的场景。如果设为 0，值会随鼠标连续变化。

基本用法​

单维 Float 滑块​

static float volume = 0.5f;
static HX::SliderProfile1f sp;
sp.MinValue = 0.0f;
sp.MaxValue = 1.0f;
HX::Slider1f(HXStr("音量"), volume, sp);
// volume 的值会随着拖拽实时变化

单维 Int 滑块（带步进）​

static int health = 100;
static HX::SliderProfile1i sp;
sp.MinValue = 0;
sp.MaxValue = 200;
sp.Step = 10;  // 每次变化 10
HX::Slider1i(HXStr("生命值"), health, sp);

四维 Float 滑块（RGBA 颜色）​

static float color[4] = {1.0f, 0.5f, 0.2f, 1.0f};
static HX::SliderProfile4f sp;
HX::Slider4f(HXStr("RGBA"), color, sp);
// 四个滑块并排显示，分别控制 R/G/B/A
生命周期警告！

SliderProfile 和 Value 都必须是 static 或全局变量。如果 Value 是局部变量，滑块在下一帧就会指向一个已经销毁的地址；如果 Profile 是局部变量，拖拽状态会每一帧重置，滑块根本无法拖动！

编辑模式（双击输入精确值）​

HiEasyX 的滑块支持一个非常实用的功能：双击数值区域，就会变成一个输入框，让你直接键盘输入精确数字。输完按回车确认，按 Esc 取消。

这个功能是自动的，不需要你额外写代码。但你可以通过读取 InEditMode 来判断用户是否正在编辑：

static float speed = 10.0f;
static HX::SliderProfile1f sp;
HX::Slider1f(HXStr("速度"), speed, sp);

if (sp.InEditMode) {
    // 用户正在输入精确值，你可以在这里暂停游戏逻辑之类的
}

自定义格式化回调​

默认情况下，滑块右侧会显示当前数值。如果你想要更友好的显示方式（比如显示百分比、添加单位后缀），可以用 FormatCallback：

static float progress = 0.75f;
static HX::SliderProfile1f sp;
sp.MinValue = 0.0f;
sp.MaxValue = 1.0f;
sp.FormatCallback = [](float v) -> HXString {
    int percent = static_cast<int>(v * 100);
    return std::to_wstring(percent) + HXStr("%");
};
HX::Slider1f(HXStr("进度"), progress, sp);
// 右侧会显示 "75%" 而不是 "0.75"

完整示例代码​

下面的示例展示了 1 维 float、1 维 int（带步进）、4 维 float（RGBA）、以及自定义格式化回调的用法。滑块的值会实时显示在下面的 Text 中。

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

int main() {
    initgraph(900, 700);
    setbkcolor(WHITE);
    cleardevice();

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

    BeginBatchDraw();

    // ===== 必须是 static 或全局变量 =====
    static HX::WindowProfile wp;
    wp.Size = {600, 550};
    wp.Position = {150, 50};

    static float volume = 0.5f;
    static HX::SliderProfile1f spVolume;
    spVolume.MinValue = 0.0f;
    spVolume.MaxValue = 1.0f;

    static int health = 100;
    static HX::SliderProfile1i spHealth;
    spHealth.MinValue = 0;
    spHealth.MaxValue = 200;
    spHealth.Step = 10;

    static float color[4] = {0.2f, 0.6f, 0.9f, 1.0f};
    static HX::SliderProfile4f spColor;

    static float progress = 0.35f;
    static HX::SliderProfile1f spProgress;
    spProgress.MinValue = 0.0f;
    spProgress.MaxValue = 1.0f;
    spProgress.FormatCallback = [](float v) -> HXString {
        return std::to_wstring(static_cast<int>(v * 100)) + HXStr("%");
    };

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

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

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

        // Float 滑块
        HX::Slider1f(HXStr("音量"), volume, spVolume);
        HX::Text(HXStr("当前音量: ") + std::to_wstring(volume));

        // Int 滑块（带步进）
        HX::Slider1i(HXStr("生命值"), health, spHealth);
        HX::Text(HXStr("当前生命: ") + std::to_wstring(health));

        // RGBA 滑块
        HX::Slider4f(HXStr("颜色 RGBA"), color, spColor);
        HX::Text(HXStr("R=") + std::to_wstring(color[0]) +
                 HXStr(" G=") + std::to_wstring(color[1]) +
                 HXStr(" B=") + std::to_wstring(color[2]) +
                 HXStr(" A=") + std::to_wstring(color[3]));

        // 自定义格式化
        HX::Slider1f(HXStr("进度"), progress, spProgress);

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

    closegraph();
    return 0;
}
小建议

如果你不确定用 float 还是 int 版本，记住这条规则：视觉参数（颜色、透明度、音量）用 f 版本；计数、索引、离散档位（生命值、等级、数量）用 i 版本。步进值 Step 在 i 版本中特别好用。

运行效果​

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

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