跳转至

列表控件 (SListCtrl)

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

基本信息

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

属性说明

自身属性

属性名 类型 默认值 说明
headerHeight layoutsize 20 表头高度
itemHeight layoutsize 20 行高
checkBox bool false 是否显示行首复选框
multiSelection bool false 是否允许多选
itemSkin string SKIN_SYS_LIST_ITEM 行背景皮肤
iconSkin string - 图标皮肤
checkSkin string SKIN_SYS_CHECKBOX 复选框皮肤
colorItemBkgnd color #ffffff 偶数行背景色
colorItemBkgnd2 color #e2e2e2 奇数行背景色
colorItemSelBkgnd color #3991d1 选中行背景色
colorItemHotBkgnd color #3991d1ff80 悬停行背景色
colorText color #000000 文本颜色
colorSelText color #ffff00 选中行文本颜色
icon-x / icon-y int -1 图标偏移
text-x / text-y int -1 文本偏移
hotTrack bool false 悬停高亮当前行

表头由内置 SHeaderCtrl 管理，其属性见表头控件。text、字体、颜色、可用、可见等通用属性见通用属性。

使用示例

基本列表

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

最佳实践

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

常见问题

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

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

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

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

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

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

相关控件