跳转至

列表控件 (SListCtrl)

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

基本信息

  • 类名：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);

最佳实践

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

常见问题

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

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

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

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

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

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

相关控件