通用属性¶

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

SOUI 中所有控件都从 SWindow 派生，因此共享一整套通用属性。这些属性由三部分组成：

SWindow 自身定义的属性
SwndStyle（窗口风格）属性 —— 通过 ATTR_CHAIN(m_style, ...) 链入
布局参数属性 —— 通过 ATTR_CHAIN_PTR(m_pLayoutParam, ...) 链入，具体可用属性取决于父容器使用的布局

各控件特有的属性请查看对应控件的文档。

源码位置 - SOUI/include/core/SWnd.h — SWindow::SOUI_ATTRS_BEGIN() - SOUI/include/core/SWndStyle.h — SwndStyle::SOUI_ATTRS_BEGIN() - SOUI/include/layout/*.h — 各布局的 SOUI_ATTRS_BEGIN() - SOUI/include/helper/SAttrCracker.h — 属性宏定义

属性宏与"默认值"的关系¶

SOUI 用宏声明 XML 属性，典型形式如下：

SOUI_ATTRS_BEGIN()
    ATTR_BOOL(L"focusable", m_bFocusable, FALSE)
    ATTR_INT(L"data", m_uData, 0)
    ATTR_CUSTOM(L"text", OnAttrText)
    ATTR_CHAIN_PTR(m_pLayoutParam, HRET_FLAG_LAYOUT_PARAM)
SOUI_ATTRS_END()

常见误解

ATTR_XXX(属性名, 成员变量, allredraw) 的第三个参数 allredraw 表示"修改该属性后是否需要整体重绘"，它不是默认值。属性的默认值来自类构造函数中对成员变量的初始化。例如 SWindow 构造时 m_bHoverAware(TRUE)，但声明写的是 ATTR_BOOL(L"hoverAware", m_bHoverAware, FALSE)，所以 hoverAware 的默认值是 true。

本页"默认值"一列均取自源码构造函数中的真实初始值。

SWindow 属性¶

属性名	类型	默认值	说明
name	string	-	控件名称，用于 `FindChildByName` 查找。同一父窗口下应唯一
id	int	-	控件整数 ID，用于 `FindChildByID` 查找及 `EVT_CMD` 命令事件路由
class	string	-	引用 `<style>` 中定义的样式类（`<class name="...">`）
text	string	-	控件文本。支持 `@string/xxx` 引用字符串表中的资源
trCtx	string	-	文本翻译上下文（多语言）
skin	string	-	背景皮肤名，支持 `skin:xxx` 形式
ncskin	string	-	非客户区皮肤名
data	int	0	用户自定义整数数据，通过 `GetUserData()/SetUserData()` 读写
enable	bool	true	是否可用。`0`/`false` 为禁用
visible	bool	true	是否可见
show	bool	true	`visible` 的同义属性，二者等价
display	bool	true	是否参与布局计算。`false` 时控件不占布局空间（区别于 `visible=false` 仍占位）
alpha	int	255	窗口整体透明度 0~255
cache	bool	false	是否启用绘制缓存（离屏渲染）。静态内容开启可提升性能
clipClient	bool	false	是否裁剪子窗口绘制到本窗口客户区
focusable	bool	false	是否可接受键盘焦点
drawFocusRect	bool	true	获得焦点时是否绘制焦点虚框
hoverAware	bool	true	是否响应鼠标 hover 状态（需父链上也为 true）
trackMouseEvent	bool	false	是否注册鼠标进入/离开跟踪（用于 `EventMouseEnter/Leave`）
videoCanvas	bool	false	是否注册为视频渲染画布
msgTransparent	bool	false	消息穿透，控件不接收鼠标/键盘消息
float	bool	false	是否浮动窗口（不参与父窗口布局）
layer	int	-	窗口在 Z 序中的层号，值越大越靠上
enableLayer	bool	false	是否启用分层绘制（layer 生效需要开启）
layeredWindow	bool	false	是否分层窗口
maxWidth	layoutsize	wrapContent	最大宽度，单位支持 `dp`/`px`/`%` 等
tip	string	-	鼠标悬停提示文本
pivotX	float	0.5	变换（旋转/缩放）中心点 X，取值 0~1 相对宽度
pivotY	float	0.5	变换（旋转/缩放）中心点 Y，取值 0~1 相对高度
layout	string	-	指定子控件使用的布局，如 `vbox`/`hbox`/`grid`
ownerLayout	string	-	指定本控件归属的布局

text 属性的特殊写法¶

text 由 SWindow::OnAttrText() 处理，支持以下形式：

<text text="普通文本"/>
<text text="@string/app_name"/>   <!-- 引用字符串表 -->

display 与 visible 的区别¶

属性	效果
`visible="0"`	控件不绘制，但仍然参与布局计算，占据空间
`display="0"`	控件不绘制，且不参与布局计算，不占空间

SwndStyle 属性（窗口风格）¶

以下属性通过 SWindow 中的 ATTR_CHAIN(m_style, HRET_FLAG_STYLE) 生效，所有控件均可用。

文本¶

属性名	类型	默认值	说明
align	enum	center	水平对齐：`left` / `center` / `right`
valign	enum	middle	垂直对齐：`top` / `middle` / `bottom`
textMode	hex	0	直接指定 `DrawText` 标志位（十六进制），优先级高于 `align`/`valign`
multiLines	bool	false	是否多行显示文本
dotted	bool	false	文本超出显示区域时是否显示省略号
font	string	-	正常状态字体
fontHover	string	-	Hover 状态字体，未指定时回退到 `font`
fontPush	string	-	Push 状态字体，未指定时回退到 `font`
fontDisable	string	-	Disable 状态字体，未指定时回退到 `font`
colorText	color	-	正常状态文本颜色
colorTextHover	color	-	Hover 状态文本颜色
colorTextPush	color	-	Push 状态文本颜色
colorTextDisable	color	-	Disable 状态文本颜色

字体回退顺序

状态字体未显式指定时，会依次回退：当前状态字体 → font → 容器默认字体。文本颜色同理。

背景与边框¶

属性名	类型	默认值	说明
colorBkgnd	color	-	背景颜色。仅在不指定 `skin` 时生效
colorBorder	color	-	边框颜色，需要与 `margin` 配合使用才会显示

边距与内边距¶

属性名	类型	默认值	说明
margin	layoutsize×4	0,0,0,0	四边外边距，顺序：左,上,右,下
margin-x	layoutsize	0	左右外边距
margin-y	layoutsize	0	上下外边距
padding	layoutsize×4	0,0,0,0	四边内边距，顺序：左,上,右,下
inset	layoutsize×4	0,0,0,0	`padding` 的同义属性
padding_left	layoutsize	0	左内边距
padding_top	layoutsize	0	上内边距
padding_right	layoutsize	0	右内边距
padding_bottom	layoutsize	0	下内边距

光标¶

属性名	类型	默认值	说明
cursor	string	arrow	鼠标光标名称，如 `arrow` / `hand` / `ibeam` / `wait` / `sizeall` 等

布局参数属性¶

布局参数由父容器决定。SWindow 默认使用 SouiLayout，此时可用 pos/width/height 等。

SouiLayout（默认布局）¶

属性名	类型	默认值	说明
pos	string	-	位置，格式 `left,top,right,bottom`。支持 `\|`（相对兄弟）、`[`/`]`（相对父窗口）、`%`、`-`/`+` 偏移
size	string	-	尺寸，格式 `width,height`
width	layoutsize	matchParent	宽度
height	layoutsize	matchParent	高度
offset	float×2	0,0	相对 `pos` 计算结果的偏移（宽度比例,高度比例）
offsetX	float	0	X 方向偏移比例
offsetY	float	0	Y 方向偏移比例

默认尺寸

SWindow 构造时执行 m_pLayoutParam->SetMatchParent(Both)，因此未指定 pos/width/height 时，控件默认填满父窗口。

LinearLayout（vbox / hbox）¶

布局自身属性（写在容器控件上）：

属性名	类型	默认值	说明
orientation	enum	horizontal	排列方向：`horizontal` / `vertical`
gravity	enum	left	子控件整体对齐方式：`left` / `top` / `center` / `right` / `bottom`
interval	layoutsize	0	子控件间距

子控件可用属性：

属性名	类型	默认值	说明
width	layoutsize	-	宽度
height	layoutsize	-	高度
size	layoutsize×2	-	尺寸 `width,height`
weight	float	0	剩余空间分配权重
layout_gravity	enum	left	本控件在布局中的对齐方式：`left` / `top` / `center` / `right` / `bottom`
extend	layoutsize×4	-	四边扩展量，顺序：左,上,右,下
extend_left	layoutsize	0	左扩展量
extend_top	layoutsize	0	上扩展量
extend_right	layoutsize	0	右扩展量
extend_bottom	layoutsize	0	下扩展量

FrameLayout（frame）¶

布局自身属性：enableDockMode（bool，是否启用停靠模式）。

子控件可用属性：

属性名	类型	默认值	说明
width	layoutsize	-	宽度
height	layoutsize	-	高度
size	layoutsize×2	-	尺寸 `width,height`
dock	enum	none	停靠位置：`none` / `left` / `top` / `right` / `bottom` / `mainview`（别名 `main`）
dockRelativeTo	string	-	停靠的相对兄弟控件名
weight	float	0	权重
layout_gravity	enum	left	对齐方式：`left` / `top` / `center` / `right` / `bottom`
extend_left / extend_top / extend_right / extend_bottom	layoutsize	0	各边扩展量

GridLayout（grid）¶

布局自身属性：

属性名	类型	默认值	说明
columnCount	int	-	列数
rowCount	int	-	行数
xInterval	layoutsize	0	水平间距
yInterval	layoutsize	0	垂直间距
interval	layoutsize	0	间距，同时设置 x 与 y
xGravity	enum	left	水平对齐：`left` / `center` / `right` / `fill`
yGravity	enum	top	垂直对齐：`top` / `center` / `bottom` / `fill`
gravity	enum	-	对齐方式，同时设置 x 与 y
orientation	enum	horizontal	排列方向：`horizontal` / `vertical`

子控件可用属性：

属性名	类型	默认值	说明
rowSpan	int	1	行跨越数
columnSpan	int	1	列跨越数
width	layoutsize	-	宽度
height	layoutsize	-	高度
size	layoutsize×2	-	尺寸 `width,height`
layout_xGravity	enum	left	水平对齐：`left` / `center` / `right` / `fill`
layout_yGravity	enum	top	垂直对齐：`top` / `center` / `bottom` / `fill`
layout_gravity	enum	-	对齐方式，同时设置 x 与 y
columnWeight	float	0	列权重
rowWeight	float	0	行权重

FlowLayout（hflow / vflow）¶

布局自身属性：

属性名	类型	默认值	说明
orientation	enum	horizontal	`horizontal`：从左到右排列，超宽换行；`vertical`：从上到下排列，超高换列
gravity	enum	left	子控件整体对齐方式：`left` / `top` / `center` / `right` / `bottom`
xInterval	layoutsize	0	水平间距
yInterval	layoutsize	0	垂直间距
interval	layoutsize	0	间距，同时设置 x 与 y

子控件可用属性同 LinearLayout。

AnchorLayout（Anchor）¶

属性名	类型	默认值	说明
pos	string	-	锚点位置
size	layoutsize×2	-	尺寸 `width,height`
width	layoutsize	-	宽度
height	layoutsize	-	高度
offset	float×2	0,0	偏移
offsetX	float	0	X 方向偏移比例
offsetY	float	0	Y 方向偏移比例

属性别名¶

部分属性存在别名，二者完全等价：

别名	等价属性
show	visible
inset	padding

详见属性别名。

通用属性¶

属性宏与"默认值"的关系¶

SWindow 属性¶

text 属性的特殊写法¶

display 与 visible 的区别¶

SwndStyle 属性（窗口风格）¶

文本¶

背景与边框¶

边距与内边距¶

光标¶

布局参数属性¶

SouiLayout（默认布局）¶

LinearLayout（vbox / hbox）¶

FrameLayout（frame）¶

GridLayout（grid）¶

FlowLayout（hflow / vflow）¶

AnchorLayout（Anchor）¶

属性别名¶

相关文档¶