SWindow 控件基类¶

SWindow 是 SOUI 控件系统的基础，绝大多数控件都继承自该类。它提供了控件的基本属性和行为。

类信息¶

类名：SWindow
控件标签：window
基类：TObjRefImpl<SObjectImpl<IWindow>>（同时以 protected 方式继承 IAnimationListener）

属性说明¶

以下为 SWindow 自身定义的属性，即 SWindow::SOUI_ATTRS_BEGIN() 中声明的全部属性。

标识属性¶

属性名	类型	默认值	说明
name	string	-	控件名称，用于 `FindChildByName` 查找。同一父窗口下应唯一
id	int	-	控件整数 ID，用于 `FindChildByID` 查找及 `EVT_CMD` 命令事件路由。支持 `IDOK`/`IDCANCEL`/`IDCLOSE`/`IDYES`/`IDNO` 等系统 ID 字符串
class	string	-	引用 `<style>` 中定义的样式类（`<class name="...">`）

外观属性¶

属性名	类型	默认值	说明
skin	skin	-	背景皮肤名，支持 `skin:xxx` 形式
ncskin	skin	-	非客户区（边框）皮肤名
alpha	int	255	窗口整体透明度，取值 0~255

状态属性¶

属性名	类型	默认值	说明
enable	bool	true	是否可用，`0`/`false` 为禁用
visible	bool	true	是否可见
show	bool	true	`visible` 的同义属性，二者等价
display	bool	true	是否参与布局计算。`false` 时控件不绘制且不占布局空间（`visible="0"` 仍占位）
cache	bool	false	是否启用绘制缓存（离屏渲染）。静态内容开启可提升性能
msgTransparent	bool	false	消息穿透，控件不拦截鼠标/键盘消息
focusable	bool	false	是否可接受键盘焦点
clipClient	bool	false	是否将子窗口绘制裁剪到本窗口客户区
layeredWindow	bool	false	是否分层窗口

布局属性¶

属性名	类型	默认值	说明
maxWidth	layoutsize	wrapContent	最大宽度，自动计算大小时生效，支持 `dp`/`px`/`%` 等单位
layer	int	0	窗口绘制层级，仅当父窗口 `enableLayer="1"` 时生效
enableLayer	bool	false	是否启用分层绘制（`layer` 生效的前提）
layout	string	-	指定子控件使用的布局，如 `vbox`/`hbox`/`grid`/`frame`/`anchor`，也可自定义布局类型
ownerLayout	string	-	指定本控件归属的布局类型。当窗口不是在主界面中初始化、而是初始化后再加入主界面时，用它可以保留特定布局类型的属性，否则可能丢失数据
float	bool	false	是否浮动窗口（不参与父窗口布局，位置固定不动）

交互属性¶

属性名	类型	默认值	说明
tip	string	-	鼠标悬停提示文本，支持 `@string/xxx` 形式
data	int	0	用户自定义整数数据，通过 `GetUserData()/SetUserData()` 读写
hoverAware	bool	true	是否响应鼠标 hover 状态（父链上的窗口也需为 true）
trackMouseEvent	bool	false	是否注册鼠标进入/离开跟踪，开启后才能收到 `EventMouseEnter`/`EventMouseLeave`
videoCanvas	bool	false	是否注册为视频渲染画布
drawFocusRect	bool	true	获得焦点时是否绘制焦点虚框

文本属性¶

属性名	类型	默认值	说明
text	string	-	控件文本，支持 `@string/xxx` 引用字符串表中的资源
trCtx	string	-	文本翻译上下文（多语言）

变换属性¶

属性名	类型	默认值	说明
pivotX	float	0.5	变换（旋转/缩放）中心点 X，取值 0~1，相对控件宽度
pivotY	float	0.5	变换（旋转/缩放）中心点 Y，取值 0~1，相对控件高度

继承自 SwndStyle 的窗口风格属性（align/valign/textMode/multiLines/dotted/font*/colorText*/colorBkgnd/colorBorder/margin/padding/cursor 等），以及各布局的布局参数属性（pos/size/width/height/offset/weight/gravity 等），见通用属性。

使用示例¶

基本窗口¶

<window pos="10,10,200,100" 
        name="basic_window"
        skin="skin_window"
        text="基本窗口"/>

带文本和样式的窗口¶

<window pos="10,110,200,200" 
        name="styled_window"
        skin="skin_styled_window"
        text="样式窗口"
        colorText="#333333"
        font="size:14,bold:1"
        align="center"
        valign="middle"/>

带边框和透明度的窗口¶

<window pos="10,210,200,300" 
        name="border_window"
        ncskin="skin_border"
        margin="2,2,2,2"
        colorBorder="#CCCCCC"
        alpha="200"
        text="带边框窗口"/>

带图层渲染的窗口¶

<window pos="10,10,200,100" 
        name="layered_window"
        skin="skin_window"
        text="图层窗口"
        enableLayer="1">
    <window layer="10" text="子窗口1"/>
    <window layer="5" text="子窗口2"/>
</window>

带提示与鼠标跟踪的窗口¶

<window pos="10,10,200,100" 
        name="animated_window"
        skin="skin_window"
        text="提示窗口"
        tip="这是一个提示"
        trackMouseEvent="1"
        hoverAware="1"
        pivotX="0.5"
        pivotY="0.5"/>

布局容器窗口¶

<window pos="220,10,410,200" 
        name="layout_window"
        layout="hbox"
        gravity="center">
    <button text="按钮1" size="80,30"/>
    <window weight="1"/> <!-- 占位窗口 -->
    <button text="按钮2" size="80,30"/>
</window>

事件处理¶

作为控件基类，SWindow支持以下基本事件：

事件名	EventID	说明
EVT_MOUSE_BEGIN	EventMouse::EventID	鼠标事件开始
EVT_MOUSE_END	EventMouse::EventID	鼠标事件结束
EVT_KEY_BEGIN	EventKey::EventID	键盘事件开始
EVT_KEY_END	EventKey::EventID	键盘事件结束
EVT_SETFOCUS	EventSetFocus::EventID	获得焦点事件
EVT_KILLFOCUS	EventKillFocus::EventID	失去焦点事件

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

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

代码操作¶

// 查找窗口控件
SWindow *pWindow = FindChildByName2<SWindow>(L"basic_window");

// 设置文本
pWindow->SetWindowText(L"新文本");

// 获取文本
SStringT strText = pWindow->GetWindowText();

// 显示/隐藏控件
pWindow->ShowWindow(SW_SHOW);  // 显示
pWindow->ShowWindow(SW_HIDE);  // 隐藏

// 启用/禁用控件
pWindow->EnableWindow(FALSE);  // 禁用
pWindow->EnableWindow(TRUE);   // 启用

// 设置焦点
pWindow->SetFocus();

// 获取控件状态
BOOL bVisible = pWindow->IsVisible();
BOOL bEnabled = pWindow->IsWindowEnabled();

最佳实践¶

合理使用皮肤：通过 skin 和 ncskin 属性定制控件外观
布局管理：使用 layout 属性指定子控件布局，配合布局参数属性实现灵活布局
状态控制：通过 enable、visible 和 display 属性控制控件状态
性能优化：适当使用 cache 和 enableLayer 属性提升渲染性能和控制绘制顺序
用户体验：使用 tip 属性提供操作提示

常见问题¶

Q: 如何精确控制控件的绘制顺序？¶

A: 设置父窗口的 enableLayer 属性为 1，然后在子窗口中使用 layer 属性设置具体的绘制层级，数值越小越靠前。

Q: 控件的旋转/缩放围绕哪里进行？¶

A: 变换默认围绕控件中心进行，可用 pivotX 和 pivotY 调整变换中心点（取值 0~1，相对控件宽高）。注意 scale/rotate 等不是 XML 属性，而是通过属性动画在代码中设置的变换名。

Q: 控件显示异常怎么办？¶

A: 检查 pos 和 size 布局参数是否设置正确，确保控件在父窗口范围内。注意未指定 pos/width/height 时，控件默认填满父窗口。详见通用属性。

Q: 控件无法响应事件怎么办？¶

A: 确保 msgTransparent 属性设置为 0，并且控件处于启用状态。

Q: 文本显示不完整怎么办？¶

A: 检查 maxWidth 属性是否限制了控件宽度，或使用 dotted 属性启用省略号显示（见通用属性）。