切换控件 (SToggle)¶

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

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

基本信息¶

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

属性说明¶

SToggle 继承自 SCheckBox，自身没有新增 XML 属性，仅改变了默认皮肤与图标间距。因此它的可用属性与 SCheckBox 完全一致：

自身属性¶

属性名	类型	默认值	说明
checked	bool	false	初始化选中状态（`1`/`true` 为开，`0`/`false` 为关）
skin	string	SKIN_SYS_TREE_TOGGLE	开关图标皮肤（内置默认皮肤，区别于 SCheckBox）
focusSkin	string	SKIN_SYS_FOCUSCHECKBOX	获得焦点时的图标皮肤
sep	int	0	图标与文本之间的间距（像素）。`SToggle` 默认 `0`（为纯开关样式）

文本（text）、字体、颜色、对齐（align / valign）、enable / visible / display 等属性继承自 SWindow / SwndStyle，详见通用属性。

使用示例¶

基础切换按钮¶

<!-- 基础切换按钮 -->
<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);   // 启用

最佳实践¶

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

常见问题¶

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

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

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

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

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

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