SWindow 控件基类

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

类信息

• 类名：SWindow
• 控件标签：window
• 基类：
• SObject
• SMsgHandleState
• TObjRefImpl2<IObjRef,SWindow>

基本属性

标识属性

属性名	类型	默认值	说明
id	字符串	-	Object ID
name	字符串	-	Object Name

外观属性

属性名	类型	默认值	说明
skin	字符串	-	皮肤
ncskin	字符串	-	边框皮肤
class	字符串	-	样式
alpha	[0-255]	-	透明度，数值在0-255之间
colorBkgnd	color	-	背景颜色，不指定skin时有效
colorBorder	color	-	边框颜色，需要和margin一起使用

状态属性

属性名	类型	默认值	说明
enable	bool	1	是否可用（是:1
visible/show	bool	1	是否可见（是:1
display	bool	1	隐藏占位（是:1
cache	bool	0	画布缓存（是:1
msgTransparent	bool	0	消息穿透（是:1
focusable	bool	1	焦点（是:1
clipClient	bool	0	裁剪客户区（是:1
blendBackground	bool	1	背景融合（是:1

布局属性

属性名	类型	默认值	说明
pos	字符串	-	位置，“
offset	字符串	-	偏移，根据pos确定位置后再做偏移，单位为控件大小，格式为水平偏移系数,垂直偏移系数
size	字符串	-	尺寸，-1 窗口自适应内容大小，-2 使用父窗口的宽/高
margin	字符串	-	边框大小，和colorBorder或者ncSkin配合使用，格式为左,上,右,下
padding	字符串	-	内边距，和inset属性相同，格式为左,上,右,下
maxWidth	数字	-	最大宽度，自动计算大小时，窗口的最大宽度
layer	数字	0	窗口的绘制层级，数值越小越靠前，仅当父窗口的enableLayer为true时生效，方便用户精确控制控件的绘制顺序
ownerLayout	字符串	soui	父窗口布局类型，当一个窗口不是在主界面中初始化，而是初始化后再加入到主界面中时，通过指定ownerLayout属性，使得后续指定的特定布局类型的属性可以保持，否则可能导致数据丢失
layout	字符串	soui	窗口布局类型，支持soui,grid,hbox,vbox, anchor 这些内置布局类型，也可以自定义布局类型

动画属性

属性名	类型	默认值	说明
scale	float	1.0	缩放比例，控制控件的整体缩放
scaleX	float	1.0	X轴方向缩放比例
scaleY	float	1.0	Y轴方向缩放比例
rotate	float	0.0	旋转角度，单位为度
translate	float	0.0	平移距离，同时控制X和Y轴方向的平移
translateX	float	0.0	X轴方向平移距离
translateY	float	0.0	Y轴方向平移距离
pivotX	float	0.5	X轴变换中心点，相对于控件宽度的比例（0.0-1.0）
pivotY	float	0.5	Y轴变换中心点，相对于控件高度的比例（0.0-1.0）

交互属性

属性名	类型	默认值	说明
tip	字符串	-	提示
data	字符串	-	用户数据
cursor	字符串	-	光标，可选值：arrow,ibeam,wait,cross,uparrow,size,sizenwse,sizenesw,sizewe,sizens,sizeall,no,hand,help
float	bool	0	float（是:1
gravity	字符串	-	子控件的对齐方式，可选值：左:left,上:top,中:center,右:right,下:bottom
layout_gravity	字符串	-	相对于父控件的对齐方式，可选值：左:left,上:top,中:center,右:right,下:bottom

文本属性

属性名	类型	默认值	说明
text	字符串	-	text value
align	字符串	-	水平对齐，可选值：left,center,right
valign	字符串	-	垂直对齐，可选值：top,middle,bottom
font	字符串	-	文本字体
fontHover	字符串	-	Hover字体
fontPush	字符串	-	Push字体
fontDisable	字符串	-	Disable字体
colorText	color	-	文本颜色
colorTextHover	color	-	Hover颜色
colorTextPush	color	-	Push颜色
colorTextDisable	color	-	Disable颜色
dotted	bool	0	省略号显示文本（是:1
drawFocusRect	bool	0	焦点虚框（是:1

使用示例

基本窗口

<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="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="动画窗口"
        scale="1.2"
        rotate="45"
        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();

最佳实践

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

常见问题

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

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

Q: 如何实现控件的缩放和旋转效果？

A: 使用 scale、scaleX、scaleY 控制缩放，使用 rotate 控制旋转角度，使用 pivotX 和 pivotY 控制变换中心点。

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

A: 检查 pos 和 size 属性是否设置正确，确保控件在父窗口范围内。

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

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

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

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

相关控件

• 按钮(SButton) - 基础交互控件
• 文本标签(SStatic) - 文本显示控件
• 面板(SPanel) - 容器控件