列表控件 (SListCtrl)¶

Warning

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

You can read it through google translate.

列表控件是一个用于显示多列数据的控件，支持列表头、列宽调整、排序等功能。它适合用于展示表格形式的数据，并提供丰富的交互功能。

基本信息¶

类名：SListCtrl
控件标签：listctrl
基类：SWindow
功能：提供多列数据显示和管理功能

属性说明¶

基本属性¶

属性名	类型	默认值	说明
headerHeight	int	-	表头控件高度
itemHeight	int	-	行高
hotTrack	bool	0	热点跟踪（0-否，1-是）
multiSelection	bool	0	是否支持多选（0-不支持，1-支持）
checkBox	bool	0	是否在第一列显示checkbox（0-不支持，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

使用示例¶

基本列表¶

``xml

列标题1 列标题2 列标题3

### 带复选框的列表
``xml
<listctrl name="lcWithCheckbox" 
          pos="10,330,510,530" 
          headerHeight="30"
          itemHeight="25"
          checkBox="1"
          multiSelection="1"
          colorItemBkgnd="#FFFFFF"
          colorItemSelBkgnd="#007ACC">
    <header align="left" itemSwapEnable="1" fixWidth="0" sortHeader="1">
        <items>
            <item width="30"></item> <!-- 复选框列 -->
            <item width="150">姓名</item>
            <item width="100">年龄</item>
            <item width="180">邮箱</item>
        </items>
    </header>
</listctrl>

自定义样式的列表¶

``xml

产品名称价格类别描述

### 隔行变色的列表
``xml
<listctrl name="lcAlternating" 
          pos="530,330,1030,530" 
          headerHeight="30"
          itemHeight="25"
          hotTrack="1"
          colorText="#333333"
          colorItemBkgnd="#FFFFFF"
          colorItemBkgnd2="#F0F0F0"
          colorItemSelBkgnd="#007ACC"
          colorSelText="#FFFFFF">
    <header align="left">
        <items>
            <item width="100">ID</item>
            <item width="150">名称</item>
            <item width="200">描述</item>
        </items>
    </header>
</listctrl>

事件处理¶

列表控件支持以下事件：

事件名	EventID	说明
EVT_LC_SELCHANGED	EventLCSelChanged::EventID	选择项改变事件
EVT_LC_ITEMDBCLICK	EventLCItemDbClick::EventID	项目双击事件
EVT_LC_CHECKSTATE	EventLCCheckState::EventID	复选框状态改变事件

``cpp // 事件处理示例 EVENT_MAP_BEGIN() EVENT_NAME_HANDLER(L"lcBasic", EventLCSelChanged::EventID, OnLCSelChanged) EVENT_NAME_HANDLER(L"lcWithCheckbox", EventLCCheckState::EventID, OnLCCheckState) EVENT_MAP_END()

void OnLCSelChanged(IEvtArgs pEvt) { EventLCSelChanged pRealEvt = sobj_cast(pEvt); int nCurSel = pRealEvt->nCurSel; // 处理选择项改变 }

void OnLCCheckState(IEvtArgs pEvt) { EventLCCheckState pRealEvt = sobj_cast(pEvt); int nItem = pRealEvt->nItem; BOOL bCheck = pRealEvt->bCheck; // 处理复选框状态改变 }

## 代码操作

``cpp
// 查找列表控件
SListCtrl *pListCtrl = FindChildByName2<SListCtrl>(L"lcBasic");

// 添加新项
int nIndex = pListCtrl->InsertItem(0, L"新项目");

// 设置子项文本
pListCtrl->SetItemText(0, 0, L"子项1");
pListCtrl->SetItemText(0, 1, L"子项2");
pListCtrl->SetItemText(0, 2, L"子项3");

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

// 获取选中项数量（多选模式下）
int nSelCount = pListCtrl->GetSelCount();

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

// 删除指定项
pListCtrl->DeleteItem(0);

// 清空所有项
pListCtrl->DeleteAllItems();

// 设置复选框状态（如果启用了复选框）
pListCtrl->SetCheckState(0, TRUE);

最佳实践¶

表头设计：合理设置 headerHeight 和列宽度，确保表头信息清晰可见
视觉反馈：使用 hotTrack 属性提供鼠标悬停反馈
交互设计：根据需要启用 multiSelection 和 checkBox 属性
样式统一：通过皮肤和颜色属性保持界面风格统一
数据展示：合理使用隔行变色提高数据可读性

常见问题¶

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

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

Q: 复选框功能不工作怎么办？¶

A: 确保设置了 checkBox 属性为 1，并正确处理 EVT_LC_CHECKSTATE 事件。

Q: 多选功能无效怎么办？¶

A: 检查是否设置了 multiSelection 属性为 1。