跳转至

切换控件 (SToggle)

切换控件提供了一个可以在两种状态之间切换的按钮，常用于开关、展开/折叠等场景，支持自定义外观和动画效果。

基本信息

  • 类名：SToggle
  • 控件标签：toggle
  • 基类：SCheckBox -> SWindow
  • 功能：提供两种状态之间的切换功能

属性说明

基本属性

属性名 类型 默认值 说明
checked bool 0 初始化时的选中状态（0-未选中，1-选中）
text string - 复选框文本
align string left 水平对齐方式（left/center/right）
valign string middle 垂直对齐方式（top/middle/bottom）

外观属性

属性名 类型 默认值 说明
skin string - 默认皮肤
focusSkin string - 焦点状态显示的皮肤
colorText color - 文本颜色
colorTextHover color - Hover状态文本颜色
colorTextPush color - Push状态文本颜色
colorTextDisable color - Disable状态文本颜色
font string - 文本字体
fontHover string - Hover状态文本字体
fontPush string - Push状态文本字体
fontDisable string - Disable状态文本字体

状态属性

属性名 类型 默认值 说明
enable bool 1 是否可用（0-不可用，1-可用）
visible bool 1 是否可见（0-不可见，1-可见）
display bool 1 控件隐藏时是否占位（0-不占位，1-占位）

使用示例

基础切换按钮

<!-- 基础切换按钮 -->
<toggle pos="10,10,60,30" name="toggle_basic"
        skin="skin_toggle"/>

默认选中的切换按钮

<!-- 默认选中的切换按钮 -->
<toggle pos="10,40,60,60" name="toggle_checked"
        skin="skin_toggle" 
        checked="1" 
        tip="点击切换状态"/>

带文本的切换按钮

<!-- 带文本的切换按钮 -->
<toggle pos="10,70,120,90" name="toggle_text"
        skin="skin_toggle_text"
        text="开关"
        colorText="#333333"
        align="center"/>

自定义样式的切换按钮

<!-- 自定义样式的切换按钮 -->
<toggle pos="10,100,120,120" name="toggle_styled"
        skin="skin_toggle_custom" 
        focusSkin="skin_toggle_focus"
        colorText="#333333"
        colorTextHover="#FF0000"/>

事件处理

切换控件支持以下事件：

事件名 EventID 说明
EVT_CMD EventCmd::EventID 命令事件（点击时触发）
EVT_STATE_CHANGED EventStateChanged::EventID 状态改变事件 
// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_COMMAND(L"toggle_basic", OnToggleBasic)
    EVENT_NAME_HANDLER(L"toggle_basic", EventStateChanged::EventID, OnToggleStateChanged)
EVENT_MAP_END()

void OnToggleBasic()
{
    SToggle *pToggle = FindChildByName2<SToggle>(L"toggle_basic");
    BOOL bChecked = pToggle->IsChecked();
    // 处理切换按钮点击
}

void OnToggleStateChanged(IEvtArgs *pEvt)
{
    EventStateChanged *pRealEvt = sobj_cast<EventStateChanged>(pEvt);
    int nNewState = pRealEvt->GetNewState();
    // 处理状态改变
}

代码操作

// 查找切换控件
SToggle *pToggle = FindChildByName2<SToggle>(L"toggle_basic");

// 获取选中状态
BOOL bChecked = pToggle->IsChecked();

// 设置选中状态
pToggle->SetCheck(TRUE);   // 选中
pToggle->SetCheck(FALSE);  // 取消选中

// 切换选中状态
pToggle->ToggleCheck();

// 启用/禁用控件
pToggle->EnableWindow(FALSE);  // 禁用
pToggle->EnableWindow(TRUE);   // 启用

最佳实践

  1. 状态初始化：通过 checked 属性设置初始状态
  2. 视觉反馈：使用 focusSkin 提供焦点状态的视觉反馈
  3. 文本样式：通过不同状态的字体和颜色属性增强用户体验
  4. 交互提示：使用 tip 属性提供操作提示

常见问题

Q: 切换按钮状态无法正确获取怎么办？

A: 确保通过正确的事件处理函数获取状态，使用 IsChecked() 方法获取当前状态。

Q: 焦点状态显示不正确怎么办？

A: 检查是否设置了 focusSkin 属性，以及控件是否具有焦点。

Q: 文本对齐效果不明显怎么办？

A: 确保切换按钮宽度足够显示对齐效果，文本区域有足够的空间。

相关控件