Skip to content

列表框控件 (SListBox)

Warning

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

You can read it through google translate.

列表框是一个用于显示多个选项的控件，允许用户从中选择一个或多个项目。它支持单选和多选模式，并可以通过自定义模板来实现复杂的列表项显示。

基本信息

  • 类名：SListBox
  • 控件标签：listbox
  • 基类：SScrollView
  • 功能：提供可滚动的项目列表，支持单选和多选

属性说明

基本属性

属性名 类型 默认值 说明
hotTrack bool 0 热点跟踪（0-否，1-是）
itemHeight int - 行高
curSel int -1 当前选中项索引

外观属性

属性名 类型 默认值 说明
itemSkin string - 列表行皮肤
iconSkin string - 图标皮肤
colorItemBkgnd color - 列表行背景颜色
colorItemBkgnd2 color - 列表行背景颜色2，颜色隔行显示时有效
colorItemSelBkgnd color - 选中行背景颜色
colorItemHotBkgnd color - 鼠标浮动的行颜色
colorText color - 文字颜色
colorSelText color - 选中文字颜色

位置属性

属性名 类型 默认值 说明
icon-x int - 图标显示位置X
icon-y int - 图标显示位置Y
text-x int - 文本显示位置X
text-y int - 文本显示位置Y

使用示例

基本列表框

<listbox name="lbBasic" 
         pos="10,10,200,200" 
         hotTrack="1"
         itemHeight="30"
         curSel="0">
    <items>
        <item text="列表项1"/>
        <item text="列表项2"/>
        <item text="列表项3"/>
    </items>
</listbox>

带图标的列表框

<listbox name="lbWithIcons" 
         pos="10,220,200,370" 
         hotTrack="1"
         itemHeight="24"
         iconSkin="skin_listbox_icons"
         icon-x="5"
         text-x="30"
         colorText="#333333"
         colorItemBkgnd="#FFFFFF"
         colorItemSelBkgnd="#007ACC">
    <items>
        <item text="主页" icon="0"/>
        <item text="设置" icon="1"/>
        <item text="帮助" icon="2"/>
        <item text="关于" icon="3"/>
    </items>
</listbox>

自定义样式的列表框

<listbox name="lbStyled" 
         pos="220,10,410,200" 
         hotTrack="1"
         itemHeight="35"
         itemSkin="skin_listbox_item"
         colorText="#333333"
         colorSelText="#FFFFFF"
         colorItemBkgnd="#F5F5F5"
         colorItemSelBkgnd="#007ACC">
    <items>
        <item text="自定义项1"/>
        <item text="自定义项2"/>
        <item text="自定义项3"/>
    </items>
</listbox>

隔行变色的列表框

<listbox name="lbAlternating" 
         pos="220,220,410,370" 
         hotTrack="1"
         itemHeight="25"
         colorText="#333333"
         colorItemBkgnd="#FFFFFF"
         colorItemBkgnd2="#F0F0F0"
         colorItemSelBkgnd="#007ACC"
         colorSelText="#FFFFFF">
    <items>
        <item text="项目1"/>
        <item text="项目2"/>
        <item text="项目3"/>
        <item text="项目4"/>
        <item text="项目5"/>
    </items>
</listbox>

事件处理

列表框控件支持以下事件：

事件名 EventID 说明
EVT_LB_SELCHANGE EventLBSelChange::EventID 选择项改变事件
EVT_LB_DBCLICK EventLBDbClick::EventID 双击事件
EVT_LB_SELCHANGED EventLBSelChanged::EventID 选择状态改变事件 
// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"lbBasic", EventLBSelChange::EventID, OnLBSelChange)
    EVENT_NAME_HANDLER(L"lbBasic", EventLBDbClick::EventID, OnLBDbClick)
EVENT_MAP_END()

void OnLBSelChange(IEvtArgs *pEvt)
{
    EventLBSelChange *pRealEvt = sobj_cast<EventLBSelChange>(pEvt);
    int nCurSel = pRealEvt->nCurSel;
    // 处理选择项改变
}

void OnLBDbClick(IEvtArgs *pEvt)
{
    EventLBDbClick *pRealEvt = sobj_cast<EventLBDbClick>(pEvt);
    int nCurSel = pRealEvt->nCurSel;
    // 处理双击事件
}

代码操作

// 查找列表框控件
SListBox *pListBox = FindChildByName2<SListBox>(L"lbBasic");

// 获取当前选中项
int nCurSel = pListBox->GetCurSel();

// 设置当前选中项
pListBox->SetCurSel(1);

// 获取选项数量
int nCount = pListBox->GetCount();

// 获取指定项文本
SStringT strText;
pListBox->GetText(0, strText);

// 添加新项
int nIndex = pListBox->AddString(L"新项目");

// 插入新项
pListBox->InsertString(1, L"插入项目");

// 删除指定项
pListBox->DeleteString(0);

// 清空所有项
pListBox->ResetContent();

最佳实践

  1. 合理设置行高：根据内容复杂度设置合适的 itemHeight 值，确保内容完整显示
  2. 视觉反馈：使用 hotTrack 属性提供鼠标悬停反馈
  3. 样式统一：通过 itemSkin 和颜色属性保持界面风格统一
  4. 图标使用：合理使用图标提高项目可识别性，注意设置图标位置
  5. 隔行变色：使用 colorItemBkgnd2 实现隔行变色，提高可读性

常见问题

Q: 列表项显示不完整怎么办？

A: 检查 itemHeight 属性是否设置合适，确保能完整显示内容。

Q: 选中项样式不明显怎么办？

A: 确保设置了 colorItemSelBkgnd 和 colorSelText 属性，形成明显对比。

Q: 图标显示位置不正确怎么办？

A: 检查 icon-x、icon-y、text-x 和 text-y 属性设置是否正确。

相关控件