绘制类 / 画笔类 / 画刷类 / 字体类

Y++ / YStudio 开发文档 · 一点滴

有状态即时绘制（类似 QPainter）。可绑定画布、任意组件、窗口或离屏位图。绑定后可在任意事件里画图（如 创建完毕、按钮单击）；运行时每帧自动叠画，不必为每个目标手写「绘制」事件。仍可写控件「绘制」事件做每帧动态叠加。

类型	声明	工厂命令（可选）	用途
`绘制类`	`绘制类 g`	`创建绘制()` → `绘制类`	绑定目标、样式、图元、路径、导出
`画笔类`	`画笔类 pen`	`创建画笔()` → `画笔类`	描边颜色/宽度/线型；经 `g.用画笔(pen)` 套用
`画刷类`	`画刷类 brush`	`创建画刷()` → `画刷类`	填充纯色或渐变；经 `g.用画刷(brush)` 套用
`字体类`	`字体类 f`	`创建字体()` → `字体类`	绘制文本或应用到控件

相关：画布控件、图片支持库、YSS 样式。

共用约定

颜色

文本格式：#AARRGGBB 或 #RRGGBB（前导 # 可省略）。6 位时 alpha 视为 FF（不透明）。

示例	含义
`"#FFFFFFFF"` / `"FFFFFFFF"`	不透明白
`"#FFFF6688"`	不透明粉红（默认试画填充色）
`"#80000000"`	半透明黑
`"#RRGGBB"`	不透明该色

线型枚举（整数）

用于 置线型 / 画笔类.置端点 / 置连接 / 置虚线。

参数	取值	含义
端点 (cap)	`0`	平
	`1`	圆
	`2`	方
连接 (join)	`0`	斜接
	`1`	圆角连接
	`2`	斜角
虚线 (dash)	`0`	实线
	`1`	虚线
	`2`	点线
	`3`	点划线

角度

单位为度。屏幕坐标下，弧/扇形/路径弧的正角为顺时针。

多边形点列

画多边形(文本点列) 支持：

"x,y;x,y;..."（分号分隔点）
"x,y,x,y,..."（逗号扁平序列）

返回类型 `无`

表示无返回值（不要写成 逻辑 或去接返回值）。

硬约束

类型名必须写完整：绘制类 / 画笔类 / 画刷类 / 字体类（不要写 Painter / QPainter）。
方法调用必须带括号：g.绑窗口()，不要写 g.绑窗口。
绑画布 / 绑组件 / 绑窗口(窗口名) 的组件名无引号，与窗口 XML 中「名称」一致。
离屏 创建位图 后须 开始绘制…结束绘制，再 到字节集 / 存文件。
不要虚构未列出的方法；控件外观优先用属性/YSS，叠加绘制用本页 API。

绘制类

绑定与解绑

绑定后坐标原点与单位取决于目标（见下表）。清空() 清除该绘制对象的保留叠层。

`绑画布`

无 g.绑画布(组件名画布名)

参数	类型	必填	默认	取值/常量	说明
画布名	组件名	是	—	设计器中的画布控件名	无引号，如 `绑画布(画布1)`

坐标：场景坐标（含视图平移/缩放）。
返回：无。

`绑组件`

无 g.绑组件(组件名目标)

参数	类型	必填	默认	取值/常量	说明
目标	组件名	是	—	任意控件名称	无引号，如 `绑组件(按钮1)`

坐标：控件客户区，(0,0) = 左上。
返回：无。

`绑窗口`

无 g.绑窗口([组件名窗口名])

参数	类型	必填	默认	取值/常量	说明
窗口名	组件名	否	当前窗口	已载入的窗口名	可 `绑窗口()` 或 `绑窗口(窗口1)`

坐标：标题栏下客户区。
返回：无。

`绑句柄`

无 g.绑句柄(长整数句柄)

参数	类型	必填	默认	取值/常量	说明
句柄	长整数	是	—	`≥1` 组件逻辑句柄，或 HWND；`0`=解绑	逻辑句柄来自控件只读属性 `句柄`（非 HWND）

返回：无。

`创建位图`

无 g.创建位图(整数宽, 整数高, [逻辑透明 = 真])

参数	类型	必填	默认	取值/常量	说明
宽	整数	是	—	`>0` 像素	离屏位图宽度
高	整数	是	—	`>0` 像素	离屏位图高度
透明	逻辑	否	`真`	`真`/`假`	是否透明底

约束：须 开始绘制…结束绘制；可用 到字节集（PNG）/存文件 导出。
返回：无。

`解绑`

无 g.解绑()

返回：无。解除当前表面/位图绑定。

绘制会话

方法	签名	返回	说明
`开始绘制`	`逻辑 g.开始绘制()`	逻辑	成功 `真`；离屏位图必用
`结束绘制`	`逻辑 g.结束绘制()`	逻辑	结束会话
`取活动`	`逻辑 g.取活动()`	逻辑	当前是否在绘制会话中

样式对象套用

方法	签名	返回	说明
`用画笔`	`无 g.用画笔(画笔类画笔)`	无	套用独立画笔对象
`用画刷`	`无 g.用画刷(画刷类画刷)`	无	套用独立画刷对象
`用字体`	`无 g.用字体(字体类字体)`	无	套用字体；若字体设了文本色，同时作为填充色

样式快捷（可省略参数）

多数参数可省略，便于试画。

`置画笔`

无 g.置画笔([文本颜色 = "#FFFFFFFF"], [小数宽度 = 1])

参数	类型	必填	默认	取值/常量	说明
颜色	文本	否	`"#FFFFFFFF"`	见「颜色」	描边色
宽度	小数	否	`1`	`>0`	线宽（像素/DIP）

`置填充`

无 g.置填充([文本颜色 = "#FFFF6688"])

参数	类型	必填	默认	取值/常量	说明
颜色	文本	否	`"#FFFF6688"`	见「颜色」	纯色填充；调用后取消渐变模式

`置线性渐变`

无 g.置线性渐变([小数 X1=0], [小数 Y1=0], [小数 X2=100], [小数 Y2=0], [文本色1="#FFFFFFFF"], [文本色2="#FF000000"])

参数	类型	必填	默认	说明
X1,Y1	小数	否	`0`,`0`	起点
X2,Y2	小数	否	`100`,`0`	终点（默认水平）
色1,色2	文本	否	白→黑	渐变两端色

`置径向渐变`

无 g.置径向渐变([小数圆心X=50], [小数圆心Y=50], [小数半径X=50], [小数半径Y=50], [文本色1="#FFFFFFFF"], [文本色2="#FF000000"])

参数	类型	必填	默认	说明
圆心X,圆心Y	小数	否	`50`,`50`	椭圆中心
半径X,半径Y	小数	否	`50`,`50`	椭圆半径
色1,色2	文本	否	白→黑	中心→边缘

`置线型`

无 g.置线型([整数端点=0], [整数连接=0], [整数虚线=0])

参数	类型	必填	默认	取值/常量
端点	整数	否	`0`	0平 / 1圆 / 2方
连接	整数	否	`0`	0斜接 / 1圆 / 2斜角
虚线	整数	否	`0`	0实 / 1虚 / 2点 / 3点划

`置抗锯齿`

无 g.置抗锯齿([逻辑开 = 真])

参数	类型	必填	默认	说明
开	逻辑	否	`真`	`真`=抗锯齿

`置不透明度`

无 g.置不透明度([小数透明度 = 1])

参数	类型	必填	默认	取值/常量	说明
透明度	小数	否	`1`	`0`～`1`	`0` 全透明，`1` 不透明

`置字体`（快捷）

无 g.置字体([文本族="Microsoft YaHei UI"], [小数大小=12], [逻辑粗体=假], [逻辑斜体=假])

参数	类型	必填	默认	说明
族	文本	否	`"Microsoft YaHei UI"`	字体族名
大小	小数	否	`12`	字号（像素）
粗体	逻辑	否	`假`
斜体	逻辑	否	`假`

`清空`

无 g.清空([文本颜色])

参数	类型	必填	默认	说明
颜色	文本	否	透明/默认	省略则清为透明叠层；有色则用该色清屏

副作用：清除该绘制对象的保留叠层。

变换与裁剪

方法	签名	返回	说明
`保存`	`无 g.保存()`	无	压入变换/裁剪状态
`恢复`	`无 g.恢复()`	无	弹出状态
`重置变换`	`无 g.重置变换()`	无	单位矩阵
`平移`	`无 g.平移(小数 X, 小数 Y)`	无
`旋转`	`无 g.旋转(小数角度)`	无	度，顺时针为正（屏幕坐标）
`缩放`	`无 g.缩放(小数 X, 小数 Y)`	无
`裁剪矩形`	`无 g.裁剪矩形(小数 X, 小数 Y, 小数宽, 小数高)`	无
`清除裁剪`	`无 g.清除裁剪()`	无

图元

除特别说明外返回均为无。矩形类图元在填充 alpha>0 时通常填充+描边；画弧 仅描边。

`画线`

无 g.画线(小数 X1, 小数 Y1, 小数 X2, 小数 Y2) — 描边。

`画矩形`

无 g.画矩形(小数 X, 小数 Y, 小数宽, 小数高)

`画圆角矩形`

无 g.画圆角矩形(小数 X, 小数 Y, 小数宽, 小数高, 小数半径)

参数	类型	必填	说明
半径	小数	是	圆角半径（像素）

`画椭圆`

无 g.画椭圆(小数 X, 小数 Y, 小数宽, 小数高) — 外接矩形。

`画弧`

无 g.画弧(小数 X, 小数 Y, 小数宽, 小数高, 小数起始角, 小数扫过角)

参数	类型	必填	说明
起始角	小数	是	度
扫过角	小数	是	度，顺时针为正

仅描边。

`画扇形`

无 g.画扇形(小数 X, 小数 Y, 小数宽, 小数高, [小数起始角=0], [小数扫过角=90])

参数	类型	必填	默认	说明
起始角	小数	否	`0`	度
扫过角	小数	否	`90`	度

填充+描边。

`画多边形`

无 g.画多边形(文本点列) — 点列格式见「共用约定」。

`画文本`

无 g.画文本(小数 X, 小数 Y, 文本内容)

`画图像`

无 g.画图像(小数 X, 小数 Y, 小数宽, 小数高, 文本路径)

参数	类型	必填	说明
路径	文本	是	图片文件路径（或工程可解析路径）

路径

方法	签名	返回
`开始路径`	`无 g.开始路径()`	无
`移动到`	`无 g.移动到(小数 X, 小数 Y)`	无
`线到`	`无 g.线到(小数 X, 小数 Y)`	无
`二次到`	`无 g.二次到(小数控制X, 小数控制Y, 小数 X, 小数 Y)`	无
`三次到`	`无 g.三次到(小数 C1X, 小数 C1Y, 小数 C2X, 小数 C2Y, 小数 X, 小数 Y)`	无
`弧到`	`无 g.弧到(小数 X, 小数 Y, 小数宽, 小数高, 小数起始角, 小数扫过角)`	无
`闭合路径`	`无 g.闭合路径()`	无
`描边路径`	`无 g.描边路径()`	无
`填充路径`	`无 g.填充路径()`	无
`填充并描边路径`	`无 g.填充并描边路径()`	无

测量与导出

方法	签名	返回	说明
`取文本宽度`	`小数 g.取文本宽度(文本内容)`	小数	DIP
`取文本高度`	`小数 g.取文本高度(文本内容)`	小数	DIP
`取宽度`	`整数 g.取宽度()`	整数	当前目标像素宽
`取高度`	`整数 g.取高度()`	整数	当前目标像素高
`到字节集`	`字节集 g.到字节集()`	字节集	PNG；多用于离屏位图
`存文件`	`逻辑 g.存文件(文本路径)`	逻辑	成功 `真`

画笔类

声明：画笔类 pen。新建默认：颜色 #FFFFFFFF，宽度 1，端点/连接/虚线均为 0。经 g.用画笔(pen) 套用到绘制类。

方法	签名	返回	默认/取值
`置颜色`	`无 pen.置颜色([文本颜色="#FFFFFFFF"])`	无	见颜色
`取颜色`	`文本 pen.取颜色()`	文本
`置宽度`	`无 pen.置宽度([小数像素=1])`	无	`>0`
`取宽度`	`小数 pen.取宽度()`	小数
`置线型`	`无 pen.置线型([整数端点=0], [整数连接=0], [整数虚线=0])`	无	见线型枚举
`置端点`	`无 pen.置端点([整数样式=0])`	无	0平/1圆/2方
`置连接`	`无 pen.置连接([整数样式=0])`	无	0斜接/1圆/2斜角
`置虚线`	`无 pen.置虚线([整数样式=0])`	无	0实/1虚/2点/3点划
`取端点`	`整数 pen.取端点()`	整数
`取连接`	`整数 pen.取连接()`	整数
`取虚线`	`整数 pen.取虚线()`	整数
`复制`	`画笔类 pen.复制()`	画笔类	独立副本
`重置`	`无 pen.重置()`	无	恢复默认白、宽1、线型全0

画刷类

声明：画刷类 brush。经 g.用画刷(brush) 套用。

模式（取模式 返回值）： 0 纯色 · 1 线性渐变 · 2 径向渐变。

方法	签名	返回	说明
`置颜色`	`无 brush.置颜色([文本颜色="#FFFF6688"])`	无	默认粉红；切到纯色模式
`取颜色`	`文本 brush.取颜色()`	文本	渐变模式下仍返回上次纯色缓存
`置线性渐变`	`无 brush.置线性渐变([小数 x1=0],[y1=0],[x2=100],[y2=0],[文本色0="#FFFFFFFF"],[文本色1="#FF000000"])`	无	模式→1
`置径向渐变`	`无 brush.置径向渐变([小数 cx=50],[cy=50],[rx=50],[ry=50],[文本色0="#FFFFFFFF"],[文本色1="#FF000000"])`	无	模式→2
`取模式`	`整数 brush.取模式()`	整数	0/1/2
`取渐变X1` / `取渐变Y1` / `取渐变X2` / `取渐变Y2`	`小数 …()`	小数	线性端点
`取渐变圆心X` / `取渐变圆心Y` / `取渐变半径X` / `取渐变半径Y`	`小数 …()`	小数	径向
`取渐变色0` / `取渐变色1`	`文本 …()`	文本
`复制`	`画刷类 brush.复制()`	画刷类
`重置`	`无 brush.重置()`	无	回到纯色默认

新建对象在首次 置颜色() 前运行时内部可为透明纯色；文档侧以 置颜色() / 置线性渐变() 显式设置为准。

字体类

声明：字体类 f。

两条用途：

g.用字体(f) — 套到绘制类画文本；若设置了文本色，同时改填充色。
f.应用到("控件名") 或控件方法 置字体(f) — 改 UI 字体。

方法	签名	返回	默认/说明
`置名称`	`逻辑 f.置名称([文本字体名="Microsoft YaHei UI"])`	逻辑
`取名称`	`文本 f.取名称()`	文本
`置字号`	`逻辑 f.置字号([整数像素=12])`	逻辑
`取字号`	`整数 f.取字号()`	整数
`置粗体`	`逻辑 f.置粗体([逻辑是否=假])`	逻辑
`取粗体`	`整数 f.取粗体()`	整数	`0`/`1`
`置倾斜`	`逻辑 f.置倾斜([逻辑是否=假])`	逻辑
`取倾斜`	`整数 f.取倾斜()`	整数	`0`/`1`
`置文本色`	`逻辑 f.置文本色(文本颜色)`	逻辑	空=应用到控件时不改前景；`用字体` 时有色才改填充
`取文本色`	`文本 f.取文本色()`	文本	未设为空
`置背景色`	`逻辑 f.置背景色(文本颜色)`	逻辑	空=不改；主要用于控件应用
`取背景色`	`文本 f.取背景色()`	文本
`重置`	`无 f.重置()`	无	雅黑 12、非粗非斜、无色覆盖
`应用到`	`逻辑 f.应用到(文本控件名)`	逻辑	控件名字符串，如 `"按钮1"`
`应用到内容`	`逻辑 f.应用到内容(文本控件名)`	逻辑	强调超级文本框正文
`应用到行号`	`逻辑 f.应用到行号(文本控件名)`	逻辑	仅超级文本框行号栏

控件侧相关方法（非字体类本体）：置字体(字体类)、置内容字体、置行号字体（见各控件文档）。

示例

创建完毕里画（自动保留）

绘制类 p

函数 主窗口.创建完毕 () {
    p.绑窗口()
    p.置填充("#FFFF6688")
    p.画文本(10, 10, "Y++")
}

样式对象

绘制类 g
画笔类 pen
画刷类 brush
字体类 f

函数 主窗口.创建完毕 () {
    g.绑窗口()
    pen.置颜色("#FFFFFFFF")
    pen.置宽度(2)
    brush.置线性渐变(0, 0, 200, 0, "#FFFF6688", "#FF4466FF")
    f.置名称("Microsoft YaHei UI")
    f.置字号(14)
    g.用画刷(brush)
    g.画矩形(10, 10, 180, 60)
    g.用画笔(pen)
    g.用字体(f)
    g.画文本(20, 28, "样式对象")
}

多数样式参数可省略：

绘制类 g
函数 主窗口.创建完毕 () {
    g.绑窗口()
    g.置填充()          // 默认粉红
    g.置画笔()          // 默认白、线宽 1
    g.置字体()          // 默认雅黑 12
    g.画矩形(10, 10, 120, 40)
    g.画文本(20, 20, "试画")
}

路径 + 渐变

绘制类 g

函数 主窗口.创建完毕 () {
    g.绑组件(图片框1)
    g.置线性渐变(0, 0, g.取宽度(), 0, "#FFFF6688", "#FF4466FF")
    g.开始路径()
    g.移动到(20, 20)
    g.线到(120, 20)
    g.二次到(140, 60, 80, 100)
    g.闭合路径()
    g.填充路径()
    g.置画笔("#FFFFFFFF", 2)
    g.描边路径()
}

离屏导出

绘制类 bmp
bmp.创建位图(256, 256, 真)
如果 (bmp.开始绘制()) {
    bmp.置径向渐变(128, 128, 120, 120, "#FFFFFFFF", "#FF224466")
    bmp.画椭圆(8, 8, 240, 240)
    bmp.结束绘制()
}
字节集 png = bmp.到字节集()
bmp.存文件("out.png")

错误用法对照

错误	正确
`Painter p` / `QPainter`	`绘制类 p`
`p.绑窗口`（无括号）	`p.绑窗口()`
`p.绑组件("按钮1")`	`p.绑组件(按钮1)`
离屏不写 `开始绘制`/`结束绘制`	创建位图后成对调用
`pen.颜色 = "#FF00"`	`pen.置颜色("#FFFF0000")`（用方法，色值 6/8 位）
线型写 `"dash"`	整数：`置虚线(1)`
角度用弧度	用度
虚构 `画圆形(x,y,r)`	用 `画椭圆` 外接矩形

API 速查

类别	方法
绑定	`绑画布` `绑组件` `绑窗口` `绑句柄` `创建位图` `解绑`
会话	`开始绘制` `结束绘制` `取活动`
样式对象	`用画笔` `用画刷` `用字体`
样式快捷	`置画笔` `置填充` `置线性渐变` `置径向渐变` `置线型` `置抗锯齿` `置不透明度` `置字体` `清空`
变换/裁剪	`保存` `恢复` `重置变换` `平移` `旋转` `缩放` `裁剪矩形` `清除裁剪`
图元	`画线` `画矩形` `画圆角矩形` `画椭圆` `画弧` `画扇形` `画多边形` `画文本` `画图像`
路径	`开始路径` `移动到` `线到` `二次到` `三次到` `弧到` `闭合路径` `描边路径` `填充路径` `填充并描边路径`
测量/导出	`取文本宽度` `取文本高度` `取宽度` `取高度` `到字节集` `存文件`
画笔类	`置/取颜色` `置/取宽度` `置线型` `置/取端点` `置/取连接` `置/取虚线` `复制` `重置`
画刷类	`置/取颜色` `置线性/径向渐变` `取模式` `取渐变*` `复制` `重置`
字体类	`置/取名称` `置/取字号` `置/取粗体` `置/取倾斜` `置/取文本色` `置/取背景色` `重置` `应用到*`