跳转至

单选框控件 (SRadioBox)

单选框是一种互斥选择控件，在一组选项中只允许选择一个选项。通常用于用户需要在多个选项中做出唯一选择的场景。

基本信息

  • 类名：SRadioBox
  • 控件标签：radio
  • 基类：SWindow
  • 功能：提供互斥的选项选择

属性说明

自身属性

属性名 类型 默认值 说明
checked bool false 初始化选中状态（1/true 为选中，0/false 为未选中）
skin string SKIN_SYS_RADIO 单选框图标皮肤（内置默认皮肤）
focusSkin string SKIN_SYS_FOCUSRADIO 获得焦点时的图标皮肤
iconAlign enum left 图标水平对齐：left / center / right（相对文本）
iconValign enum middle 图标垂直对齐：top / middle / bottom（相对文本）
sep int 4 图标与文本之间的间距（像素）

文本（text）、字体、颜色、对齐（align / valign）、enable / visible / display 等属性 继承自 SWindow / SwndStyle，详见通用属性。 单选框通过 SRadioGroup（radioGroup 标签）实现同组互斥，同一父容器下多个 <radio> 默认按父窗口分组互斥。

使用示例

基本单选框组

<window>
    <radio name="radio1" 
           pos="10,10,150,30" 
           text="选项1" 
           checked="1"/>
    <radio name="radio2" 
           pos="10,40,150,60" 
           text="选项2"/>
    <radio name="radio3" 
           pos="10,70,150,90" 
           text="选项3"/>
</window>

（移除分组单选框示例，因为分组使用方式已在"最佳实践"中说明）

（保持这部分内容不变，因为自定义样式示例已经正确）

事件处理

单选框控件支持以下事件：

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

void OnRadio1()
{
    // 处理单选框点击
}

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

分组管理

创建分组

// 查找分组中的选中项
SRadioBox *FindCheckedInGroup(const SStringW &groupName)
{
    SWindow *pRoot = GetRoot();
    SWindow::Iterator it(pRoot);
    while(*it) {
        SRadioBox *pRadio = sobj_cast<SRadioBox>(*it);
        if(pRadio && pRadio->GetGroupName() == groupName 
           && pRadio->IsChecked()) {
            return pRadio;
        }
        ++it;
    }
    return NULL;
}

组操作示例

// 选中指定组中的项
void SelectGroupItem(const SStringW &groupName, int index)
{
    int curIndex = 0;
    SWindow *pRoot = GetRoot();
    SWindow::Iterator it(pRoot);
    while(*it) {
        SRadioBox *pRadio = sobj_cast<SRadioBox>(*it);
        if(pRadio && pRadio->GetGroupName() == groupName) {
            pRadio->SetCheck(curIndex == index);
            curIndex++;
        }
        ++it;
    }
}

样式定制

自定义皮肤

<style>
    <class name="radioStyle"
           font="face:微软雅黑,size:14"
           colorText="#333333"
           skin="skin_radio"/>
</style>

<radio class="radioStyle"
       text="样式化单选框"/>

状态定制

单选框支持多种状态的外观定制： - 未选中状态 - 选中状态 - 禁用状态 - 焦点状态

最佳实践

  1. 合理分组：将相关的单选框放在同一容器内，形成逻辑组
  2. 默认选项：为单选框组设置一个合理的默认选中项
  3. 视觉反馈：使用 focusSkin 提供焦点状态的视觉反馈
  4. 文本样式：通过不同状态的字体和颜色属性增强用户体验
  5. 语义标签：为每个选项提供清晰明确的文本标签

常见问题

选中状态异常

  • 检查分组设置
  • 确认事件处理逻辑
  • 验证互斥性

外观问题

  • 检查皮肤资源
  • 确认样式设置
  • 验证状态切换

事件响应

  • 检查事件绑定
  • 确认控件状态
  • 验证分组逻辑

相关控件