SWindow 控件基类¶
Warning
The current page still doesn't have a translation for this language.
You can read it through google translate.
SWindow 是 SOUI 控件系统的基础，绝大多数控件都继承自该类。它提供了控件的基本属性和行为。
类信息¶
- 类名：
SWindow - 控件标签：
window - 基类：
SObjectSMsgHandleStateTObjRefImpl2<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();
最佳实践¶
- 合理使用皮肤：通过 skin 和 ncskin 属性定制控件外观
- 布局管理：使用 layout、gravity 和 layout_gravity 属性实现灵活布局
- 状态控制：通过 enable、visible 和 display 属性控制控件状态
- 性能优化：适当使用 cache 和 enableLayer 属性提升渲染性能和控制绘制顺序
- 用户体验：使用 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) - 容器控件