分组框控件 (SGroup)¶

分组框控件用于将相关的控件组织在一个可视的边框内，通常带有标题文本，用于创建有层次感的界面布局。

基本信息¶

类名：SGroup
控件标签：group
基类：SWindow
功能：提供带标题的分组框容器

属性说明¶

自身属性¶

属性名	类型	默认值	说明
colorLine1	color	#F0F0F0	分组框 3D 边框的高亮色（左上侧线条）
colorLine2	color	#A0A0A0	分组框 3D 边框的暗色（右下侧线条）
round	layoutsize	4dp	分组框圆角半径，支持 `dp`/`px` 等单位
headerHeight	layoutsize	20dp	头部（标题所在区域）高度，同时用于子控件布局区域的左/右缩进

标题与布局

标题文本取自通用的 text 属性，水平位置由 align 决定（仅 center 时会居中，否则左对齐）。 SGroup::GetChildrenLayoutRect() 会按 headerHeight 让子控件避开标题区域。

继承自 SWindow / SwndStyle / 布局参数的通用属性，见通用属性。

使用示例¶

基本分组框¶

<group pos="10,10,210,110" 
       name="group_basic"
       text="基本信息">
    <window pos="10,20,190,90">
        <!-- 分组框内的控件 -->
    </window>
</group>

带样式的分组框¶

<group pos="10,120,210,220" 
       name="group_styled"
       text="高级设置"
       align="center"
       round="4dp"
       headerHeight="24dp"
       colorLine1="#CCCCCC"
       colorLine2="#999999"
       colorText="#333333"
       font="bold:1,size:16">
    <window pos="10,20,190,90">
        <!-- 分组框内的控件 -->
    </window>
</group>

自定义边框的分组框¶

<group pos="220,10,420,150" 
       name="group_bordered"
       text="自定义边框"
       colorLine1="#FF0000"
       colorLine2="#0000FF"
       margin="2,2,2,2">
    <window pos="10,20,190,90">
        <!-- 分组框内的控件 -->
    </window>
</group>

右对齐标题的分组框¶

<group pos="220,160,420,260" 
       name="group_right"
       text="右对齐标题"
       align="right"
       colorText="#666666">
    <window pos="10,20,190,90">
        <!-- 分组框内的控件 -->
    </window>
</group>

事件处理¶

分组框控件支持以下事件：

事件名	EventID	说明
EVT_MOUSE_HOVER	EventMouse::EventID	鼠标悬停事件
EVT_MOUSE_LEAVE	EventMouse::EventID	鼠标离开事件
EVT_SETFOCUS	EventSetFocus::EventID	获得焦点事件
EVT_KILLFOCUS	EventKillFocus::EventID	失去焦点事件

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"group_basic", EventMouse::EventID, OnGroupMouseEvent)
EVENT_MAP_END()

void OnGroupMouseEvent(IEvtArgs *pEvt)
{
    // 处理鼠标事件
}

代码操作¶

// 查找分组框控件
SGroup *pGroup = FindChildByName2<SGroup>(L"group_basic");

// 设置标题文本
pGroup->SetWindowText(L"新标题");

// 获取标题文本
SStringT strText = pGroup->GetWindowText();

// 设置文本对齐方式
pGroup->SetAttribute(L"align", L"center");

// 设置圆角大小
pGroup->SetAttribute(L"round", L"8");

// 设置线条颜色
pGroup->SetAttribute(L"colorLine1", L"#FF0000");
pGroup->SetAttribute(L"colorLine2", L"#0000FF");

最佳实践¶

视觉分组：使用分组框将相关的控件组织在一起，提高界面的逻辑性和可读性
标题对齐：根据界面布局选择合适的标题对齐方式
样式统一：通过颜色和字体属性保持分组框样式与整体界面风格一致
间距控制：合理设置子控件与分组框边界的间距，确保布局美观

常见问题¶

Q: 分组框标题显示不完整怎么办？¶

A: 检查 headerHeight 是否足够显示标题文本，或调整字体大小（font）。

Q: 分组框边框显示异常怎么办？¶

A: 确保正确设置了 colorLine1 和 colorLine2 属性。

Q: 子控件位置不正确怎么办？¶

A: 检查子控件的 pos 布局参数是否相对于分组框正确设置；注意子控件布局区域会被 headerHeight 缩进（见通用属性）。