列表框控件 (SListBox)¶

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

基本信息¶

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

属性说明¶

自身属性¶

属性名	类型	默认值	说明
itemHeight	layoutsize	-1	单项高度（像素）。`-1` 时按内容自适应（wrapContent）
itemSkin	string	SKIN_SYS_LIST_ITEM	项背景皮肤
iconSkin	string	-	项图标皮肤
colorItemBkgnd	color	-	偶数项背景色
colorItemBkgnd2	color	-	奇数项背景色
colorItemSelBkgnd	color	#3991d1	选中项背景色
colorItemHotBkgnd	color	#3991d1ff80	悬停项背景色
colorText	color	-	文本颜色
colorSelText	color	-	选中项文本颜色
icon-x / icon-y	layoutsize	-1	图标相对项左上角的偏移
text-x / text-y	layoutsize	-1	文本相对项左上角的偏移
hotTrack	bool	false	鼠标悬停时是否高亮当前项

text、字体、颜色、可用、可见等通用属性见通用属性。列表项通过数据适配器或 AddString 添加。

使用示例¶

基本列表框¶

<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();

最佳实践¶

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

常见问题¶

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

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

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

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

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

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