awtk/docs/manual/canvas_t.md

## canvas\_t
### 概述
canvas类。

----------------------------------
### 函数
<p id="canvas_t_methods">

| 函数名称 | 说明 | 
| -------- | ------------ | 
| <a href="#canvas_t_canvas_cast">canvas\_cast</a> | 转换为canvas对象(供脚本语言使用)。 |
| <a href="#canvas_t_canvas_draw_hline">canvas\_draw\_hline</a> | 画水平线。 |
| <a href="#canvas_t_canvas_draw_icon">canvas\_draw\_icon</a> | 绘制图标。 |
| <a href="#canvas_t_canvas_draw_image">canvas\_draw\_image</a> | 绘制图片。 |
| <a href="#canvas_t_canvas_draw_points">canvas\_draw\_points</a> | 画多个点。 |
| <a href="#canvas_t_canvas_draw_text">canvas\_draw\_text</a> | 绘制文本。 |
| <a href="#canvas_t_canvas_draw_text_in_rect">canvas\_draw\_text\_in\_rect</a> | 绘制文本。 |
| <a href="#canvas_t_canvas_draw_utf8">canvas\_draw\_utf8</a> | 绘制文本。 |
| <a href="#canvas_t_canvas_draw_utf8_in_rect">canvas\_draw\_utf8\_in\_rect</a> | 绘制文本。 |
| <a href="#canvas_t_canvas_draw_vline">canvas\_draw\_vline</a> | 画垂直线。 |
| <a href="#canvas_t_canvas_fill_rect">canvas\_fill\_rect</a> | 填充矩形。 |
| <a href="#canvas_t_canvas_get_clip_rect">canvas\_get\_clip\_rect</a> | 获取裁剪区。 |
| <a href="#canvas_t_canvas_get_height">canvas\_get\_height</a> | 获取画布的高度。 |
| <a href="#canvas_t_canvas_get_vgcanvas">canvas\_get\_vgcanvas</a> | 获取vgcanvas对象。 |
| <a href="#canvas_t_canvas_get_width">canvas\_get\_width</a> | 获取画布的宽度。 |
| <a href="#canvas_t_canvas_init">canvas\_init</a> | 初始化，系统内部调用。 |
| <a href="#canvas_t_canvas_measure_text">canvas\_measure\_text</a> | 计算文本所占的宽度。 |
| <a href="#canvas_t_canvas_measure_utf8">canvas\_measure\_utf8</a> | 计算文本所占的宽度。 |
| <a href="#canvas_t_canvas_reset">canvas\_reset</a> | 释放相关资源。 |
| <a href="#canvas_t_canvas_set_clip_rect">canvas\_set\_clip\_rect</a> | 设置裁剪区。 |
| <a href="#canvas_t_canvas_set_clip_rect_ex">canvas\_set\_clip\_rect\_ex</a> | 设置裁剪区。 |
| <a href="#canvas_t_canvas_set_fill_color">canvas\_set\_fill\_color</a> | 设置填充颜色。 |
| <a href="#canvas_t_canvas_set_fill_color_str">canvas\_set\_fill\_color\_str</a> | 设置填充颜色。 |
| <a href="#canvas_t_canvas_set_font">canvas\_set\_font</a> | 设置字体。 |
| <a href="#canvas_t_canvas_set_global_alpha">canvas\_set\_global\_alpha</a> | 设置全局alpha值。 |
| <a href="#canvas_t_canvas_set_stroke_color">canvas\_set\_stroke\_color</a> | 设置线条颜色。 |
| <a href="#canvas_t_canvas_set_stroke_color_str">canvas\_set\_stroke\_color\_str</a> | 设置线条颜色。 |
| <a href="#canvas_t_canvas_set_text_align">canvas\_set\_text\_align</a> | 设置文本对齐方式。 |
| <a href="#canvas_t_canvas_set_text_color">canvas\_set\_text\_color</a> | 设置文本颜色。 |
| <a href="#canvas_t_canvas_set_text_color_str">canvas\_set\_text\_color\_str</a> | 设置文本颜色。 |
| <a href="#canvas_t_canvas_stroke_rect">canvas\_stroke\_rect</a> | 绘制矩形。 |
| <a href="#canvas_t_canvas_translate">canvas\_translate</a> | 平移原点坐标。 |
| <a href="#canvas_t_canvas_untranslate">canvas\_untranslate</a> | 反向平移原点坐标。 |
### 属性
<p id="canvas_t_properties">

| 属性名称 | 类型 | 说明 | 
| -------- | ----- | ------------ | 
| <a href="#canvas_t_ox">ox</a> | xy\_t | x坐标偏移。 |
| <a href="#canvas_t_oy">oy</a> | xy\_t | y坐标偏移。 |
#### canvas\_cast 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_cast">转换为canvas对象(供脚本语言使用)。


* 函数原型：

```
canvas_t* canvas_cast (canvas_t* c);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | canvas\_t* | canvas对象。 |
| c | canvas\_t* | canvas对象。 |
#### canvas\_draw\_hline 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_hline">画水平线。


* 函数原型：

```
ret_t canvas_draw_hline (canvas_t* c, xy_t x, xy_t y, wh_t w);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
| w | wh\_t | 宽度。 |
#### canvas\_draw\_icon 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_icon">绘制图标。


* 函数原型：

```
ret_t canvas_draw_icon (canvas_t* c, bitmap_t* img, xy_t cx, xy_t cy);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| img | bitmap\_t* | 图片对象。 |
| cx | xy\_t | 中心点x坐标。 |
| cy | xy\_t | 中心点y坐标。 |
#### canvas\_draw\_image 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_image">绘制图片。


* 函数原型：

```
ret_t canvas_draw_image (canvas_t* c, bitmap_t* img, rect_t* src, rect_t* dst);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| img | bitmap\_t* | 图片对象。 |
| src | rect\_t* | 源区域。 |
| dst | rect\_t* | 目的区域。 |
#### canvas\_draw\_points 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_points">画多个点。


* 函数原型：

```
ret_t canvas_draw_points (canvas_t* c, const point_t* points, uint32_t nr);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| points | const point\_t* | 点数组。 |
| nr | uint32\_t | 点的个数。 |
#### canvas\_draw\_text 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_text">绘制文本。


* 函数原型：

```
ret_t canvas_draw_text (canvas_t* c, const wchar_t* str, uint32_t nr, xy_t x, xy_t y);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| str | const wchar\_t* | 字符串。 |
| nr | uint32\_t | 字符数。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
#### canvas\_draw\_text\_in\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_text_in_rect">绘制文本。


* 函数原型：

```
ret_t canvas_draw_text_in_rect (canvas_t* c, const wchar_t* str, uint32_t nr, const rect_t* r);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| str | const wchar\_t* | 字符串。 |
| nr | uint32\_t | 字符数。 |
| r | const rect\_t* | 矩形区域。 |
#### canvas\_draw\_utf8 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_utf8">绘制文本。
> 供脚本语言使用。


* 函数原型：

```
ret_t canvas_draw_utf8 (canvas_t* c, const char* str, xy_t x, xy_t y);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| str | const char* | 字符串。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
#### canvas\_draw\_utf8\_in\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_utf8_in_rect">绘制文本。
> 供脚本语言使用。


* 函数原型：

```
ret_t canvas_draw_utf8_in_rect (canvas_t* c, const char* str, const rect_t* r);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| str | const char* | 字符串。 |
| r | const rect\_t* | 矩形区域。 |
#### canvas\_draw\_vline 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_draw_vline">画垂直线。


* 函数原型：

```
ret_t canvas_draw_vline (canvas_t* c, xy_t x, xy_t y, wh_t h);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
| h | wh\_t | 高度。 |
#### canvas\_fill\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_fill_rect">填充矩形。


* 函数原型：

```
ret_t canvas_fill_rect (canvas_t* c, xy_t x, xy_t y, wh_t w, wh_t h);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
| w | wh\_t | 宽度。 |
| h | wh\_t | 高度。 |
#### canvas\_get\_clip\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_get_clip_rect">获取裁剪区。


* 函数原型：

```
ret_t canvas_get_clip_rect (canvas_t* c, rect_t* r);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| r | rect\_t* | rect对象。 |
#### canvas\_get\_height 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_get_height">获取画布的高度。


* 函数原型：

```
wh_t canvas_get_height (canvas_t* c);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | wh\_t | 返回画布的高度。 |
| c | canvas\_t* | canvas对象。 |
#### canvas\_get\_vgcanvas 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_get_vgcanvas">获取vgcanvas对象。


* 函数原型：

```
vgcanvas_t* canvas_get_vgcanvas (canvas_t* c);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | vgcanvas\_t* | 返回vgcanvas对象。 |
| c | canvas\_t* | canvas对象。 |
#### canvas\_get\_width 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_get_width">获取画布的宽度。


* 函数原型：

```
wh_t canvas_get_width (canvas_t* c);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | wh\_t | 返回画布的宽度。 |
| c | canvas\_t* | canvas对象。 |
#### canvas\_init 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_init">初始化，系统内部调用。


* 函数原型：

```
canvas_t* canvas_init (canvas_t* c, lcd_t* lcd, font_manager_t* font_manager);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | canvas\_t* | 返回canvas对象本身。 |
| c | canvas\_t* | canvas对象。 |
| lcd | lcd\_t* | lcd对象。 |
| font\_manager | font\_manager\_t* | 字体管理器对象。 |
#### canvas\_measure\_text 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_measure_text">计算文本所占的宽度。


* 函数原型：

```
float_t canvas_measure_text (canvas_t* c, const wchar_t* str, uint32_t nr);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | float\_t | 返回文本所占的宽度。 |
| c | canvas\_t* | canvas对象。 |
| str | const wchar\_t* | 字符串。 |
| nr | uint32\_t | 字符数。 |
#### canvas\_measure\_utf8 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_measure_utf8">计算文本所占的宽度。
> 供脚本语言使用。


* 函数原型：

```
float_t canvas_measure_utf8 (canvas_t* c, const char* str);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | float\_t | 返回文本所占的宽度。 |
| c | canvas\_t* | canvas对象。 |
| str | const char* | 字符串。 |
#### canvas\_reset 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_reset">释放相关资源。


* 函数原型：

```
ret_t canvas_reset (canvas_t* c);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
#### canvas\_set\_clip\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_clip_rect">设置裁剪区。


* 函数原型：

```
ret_t canvas_set_clip_rect (canvas_t* c, const rect_t* r);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| r | const rect\_t* | rect对象。 |
#### canvas\_set\_clip\_rect\_ex 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_clip_rect_ex">设置裁剪区。


* 函数原型：

```
ret_t canvas_set_clip_rect_ex (canvas_t* c, const rect_t* r, bool_t translate);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| r | const rect\_t* | rect对象。 |
| translate | bool\_t | 是否将裁剪区的位置加上canvas当前的偏移。 |
#### canvas\_set\_fill\_color 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_fill_color">设置填充颜色。


* 函数原型：

```
ret_t canvas_set_fill_color (canvas_t* c, color_t color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | color\_t | 颜色。 |
#### canvas\_set\_fill\_color\_str 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_fill_color_str">设置填充颜色。
> 供脚本语言使用。


* 函数原型：

```
ret_t canvas_set_fill_color_str (canvas_t* c, const char* color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | const char* | 颜色。 |
#### canvas\_set\_font 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_font">设置字体。


* 函数原型：

```
ret_t canvas_set_font (canvas_t* c, const char* name, font_size_t size);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| name | const char* | 字体名称。 |
| size | font\_size\_t | 字体大小。 |
#### canvas\_set\_global\_alpha 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_global_alpha">设置全局alpha值。


* 函数原型：

```
ret_t canvas_set_global_alpha (canvas_t* c, uint8_t alpha);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| alpha | uint8\_t | alpha值。 |
#### canvas\_set\_stroke\_color 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_stroke_color">设置线条颜色。


* 函数原型：

```
ret_t canvas_set_stroke_color (canvas_t* c, color_t color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | color\_t | 颜色。 |
#### canvas\_set\_stroke\_color\_str 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_stroke_color_str">设置线条颜色。
> 供脚本语言使用。


* 函数原型：

```
ret_t canvas_set_stroke_color_str (canvas_t* c, const char* color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | const char* | 颜色。 |
#### canvas\_set\_text\_align 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_text_align">设置文本对齐方式。


* 函数原型：

```
ret_t canvas_set_text_align (canvas_t* c, align_h_t align_h, align_v_t align_v);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| align\_h | align\_h\_t | 水平对齐方式。 |
| align\_v | align\_v\_t | 垂直对齐方式。 |
#### canvas\_set\_text\_color 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_text_color">设置文本颜色。


* 函数原型：

```
ret_t canvas_set_text_color (canvas_t* c, color_t color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | color\_t | 颜色。 |
#### canvas\_set\_text\_color\_str 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_set_text_color_str">设置文本颜色。
> 供脚本语言使用。


* 函数原型：

```
ret_t canvas_set_text_color_str (canvas_t* c, const char* color);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| color | const char* | 颜色。 |
#### canvas\_stroke\_rect 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_stroke_rect">绘制矩形。


* 函数原型：

```
ret_t canvas_stroke_rect (canvas_t* c, xy_t x, xy_t y, wh_t w, wh_t h);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| x | xy\_t | x坐标。 |
| y | xy\_t | y坐标。 |
| w | wh\_t | 宽度。 |
| h | wh\_t | 高度。 |
#### canvas\_translate 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_translate">平移原点坐标。


* 函数原型：

```
ret_t canvas_translate (canvas_t* c, xy_t dx, xy_t dy);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| dx | xy\_t | x偏移。 |
| dy | xy\_t | y偏移。 |
#### canvas\_untranslate 函数
-----------------------

* 函数功能：

> <p id="canvas_t_canvas_untranslate">反向平移原点坐标。


* 函数原型：

```
ret_t canvas_untranslate (canvas_t* c, xy_t dx, xy_t dy);
```

* 参数说明：

| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
| c | canvas\_t* | canvas对象。 |
| dx | xy\_t | x偏移。 |
| dy | xy\_t | y偏移。 |
#### ox 属性
-----------------------
> <p id="canvas_t_ox">x坐标偏移。


* 类型：xy\_t

| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化   | 是 |
#### oy 属性
-----------------------
> <p id="canvas_t_oy">y坐标偏移。


* 类型：xy\_t

| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化   | 是 |