1# @ohos.graphics.drawing (Drawing) 2 3The Drawing module provides basic drawing capabilities, such as drawing rectangles, circles, points, straight lines, custom paths, and fonts. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - This module uses the physical pixel unit, px. 10> 11> - The module operates under a single-threaded model. The caller needs to manage thread safety and context state transitions. 12 13## Modules to Import 14 15```ts 16import { drawing } from '@kit.ArkGraphics2D'; 17``` 18 19## BlendMode 20 21Enumerates the blend modes. In blend mode, each operation generates a new color from two colors (source color and target color). These operations are the same on the four channels (red, green, blue, and alpha). The operations for the alpha channel are used as examples. 22 23For brevity, the following abbreviations are used: 24 25**s**: source. **d**: destination. **sa**: source alpha. **da**: destination alpha. 26 27The following abbreviations are used in the calculation result: 28 29**r**: The calculation methods of the four channels are the same. **ra**: Only the alpha channel is manipulated. **rc**: The other three color channels are manipulated. 30 31The table below shows the effect of each blend mode, where the yellow rectangle is the source and the blue circle is the destination. 32 33**System capability**: SystemCapability.Graphics.Drawing 34 35| Name | Value | Description | Diagram | 36| ----------- | ---- | ------------------------------------------------------------ | -------- | 37| CLEAR | 0 | Clear mode. r = 0. |  | 38| SRC | 1 | r = s (The four channels of **result** are equal to the four channels of **source**, that is, the result is equal to the source.)|  | 39| DST | 2 | r = d (The four channels of **result** are equal to the four channels of **destination**, that is, the result is equal to the destination.)|  | 40| SRC_OVER | 3 | r = s + (1 - sa) * d |  | 41| DST_OVER | 4 | r = d + (1 - da) * s |  | 42| SRC_IN | 5 | r = s * da |  | 43| DST_IN | 6 | r = d * sa |  | 44| SRC_OUT | 7 | r = s * (1 - da) |  | 45| DST_OUT | 8 | r = d * (1 - sa) |  | 46| SRC_ATOP | 9 | r = s * da + d * (1 - sa) |  | 47| DST_ATOP | 10 | r = d * sa + s * (1 - da) |  | 48| XOR | 11 | r = s * (1 - da) + d * (1 - sa) |  | 49| PLUS | 12 | r = min(s + d, 1) |  | 50| MODULATE | 13 | r = s * d |  | 51| SCREEN | 14 | Screen mode. r = s + d - s * d |  | 52| OVERLAY | 15 | Overlay mode. |  | 53| DARKEN | 16 | Darken mode. rc = s + d - max(s * da, d * sa), ra = s + (1 - sa) * d |  | 54| LIGHTEN | 17 | Lighten mode. rc = rc = s + d - min(s * da, d * sa), ra = s + (1 - sa) * d |  | 55| COLOR_DODGE | 18 | Color dodge mode. |  | 56| COLOR_BURN | 19 | Color burn mode. |  | 57| HARD_LIGHT | 20 | Hard light mode. |  | 58| SOFT_LIGHT | 21 | Soft light mode. |  | 59| DIFFERENCE | 22 | Difference mode. rc = s + d - 2 * (min(s * da, d * sa)), ra = s + (1 - sa) * d |  | 60| EXCLUSION | 23 | Exclusion mode. rc = s + d - two(s * d), ra = s + (1 - sa) * d |  | 61| MULTIPLY | 24 | Multiply mode. r = s * (1 - da) + d * (1 - sa) + s * d |  | 62| HUE | 25 | Hue mode. |  | 63| SATURATION | 26 | Saturation mode. |  | 64| COLOR | 27 | Color mode. |  | 65| LUMINOSITY | 28 | Luminosity mode. |  | 66 67## PathMeasureMatrixFlags<sup>12+</sup> 68 69Enumerates the types of matrix information obtained during path measurement. 70 71**System capability**: SystemCapability.Graphics.Drawing 72 73| Name | Value | Description | 74| ----------- | ---- | ------------------------------------------------------------ | 75| GET_POSITION_MATRIX | 0 | Matrix corresponding to the position information. | 76| GET_TANGENT_MATRIX | 1 | Matrix corresponding to the tangent information.| 77| GET_POSITION_AND_TANGENT_MATRIX | 2 | Matrix corresponding to the position and tangent information.| 78 79## SrcRectConstraint<sup>12+</sup> 80 81Enumerates the constraint types of the source rectangle. 82 83**System capability**: SystemCapability.Graphics.Drawing 84 85| Name | Value | Description | 86| ----------- | ---- | ------------------------------------------------------------ | 87| STRICT | 0 | The sampling range is strictly confined to the source rectangle, resulting in a slow sampling speed. | 88| FAST | 1 | The sampling range is not limited to the source rectangle and can extend beyond it, allowing for a high sampling speed.| 89 90## ShadowFlag<sup>12+</sup> 91 92Enumerates the flags used to control shadow drawing to create various shadow effects. 93 94**System capability**: SystemCapability.Graphics.Drawing 95 96| Name | Value | Description | 97| -------------------------- | ---- | ------------------ | 98| NONE | 0 | None of the flags are enabled. | 99| TRANSPARENT_OCCLUDER | 1 | The occluder is transparent. | 100| GEOMETRIC_ONLY | 2 | Only the geometric shadow effect is used. | 101| ALL | 3 | All the flags are enabled.| 102 103## PathOp<sup>12+</sup> 104 105Enumerates the operation modes available for a path. 106 107**System capability**: SystemCapability.Graphics.Drawing 108 109| Name | Value | Description | 110| ---------------------- | ---- | ------------------------------ | 111| DIFFERENCE | 0 | Difference operation.| 112| INTERSECT | 1 | Intersection operation.| 113| UNION | 2 | Union operation.| 114| XOR | 3 | XOR operation.| 115| REVERSE_DIFFERENCE | 4 | Reverse difference operation.| 116 117## Path 118 119A compound geometric path consisting of line segments, arcs, quadratic Bezier curves, and cubic Bezier curves. 120 121### constructor<sup>12+</sup> 122 123constructor() 124 125Constructs a path. 126 127**System capability**: SystemCapability.Graphics.Drawing 128 129**Example** 130 131```ts 132import { drawing } from '@kit.ArkGraphics2D'; 133let path: drawing.Path = new drawing.Path(); 134``` 135 136### constructor<sup>12+</sup> 137 138constructor(path: Path) 139 140Constructs a copy of an existing path. 141 142**System capability**: SystemCapability.Graphics.Drawing 143 144**Parameters** 145 146| Name | Type | Mandatory| Description | 147| -------- | -------------------------------------------- | ---- | ------------------------------- | 148| path | [Path](#path) | Yes | Path to copy. | 149 150**Example** 151 152```ts 153import { drawing } from '@kit.ArkGraphics2D'; 154let path: drawing.Path = new drawing.Path(); 155path.moveTo(0, 0); 156path.lineTo(0, 700); 157path.lineTo(700, 0); 158path.close(); 159let path1: drawing.Path = new drawing.Path(path); 160``` 161 162### moveTo 163 164moveTo(x: number, y: number) : void 165 166Sets the start point of this path. 167 168**System capability**: SystemCapability.Graphics.Drawing 169 170**Parameters** 171 172| Name| Type | Mandatory| Description | 173| ------ | ------ | ---- | ----------------------- | 174| x | number | Yes | X coordinate of the start point. The value is a floating point number.| 175| y | number | Yes | Y coordinate of the start point. The value is a floating point number.| 176 177**Error codes** 178 179For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 180 181| ID| Error Message| 182| ------- | --------------------------------------------| 183| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 184 185**Example** 186 187```ts 188import { drawing } from '@kit.ArkGraphics2D'; 189let path = new drawing.Path(); 190path.moveTo(10,10); 191``` 192 193### lineTo 194 195lineTo(x: number, y: number) : void 196 197Draws a line segment from the last point of this path to the target point. If the path is empty, the start point (0, 0) is used. 198 199**System capability**: SystemCapability.Graphics.Drawing 200 201**Parameters** 202 203| Name| Type | Mandatory| Description | 204| ------ | ------ | ---- | ----------------------- | 205| x | number | Yes | X coordinate of the target point. The value is a floating point number.| 206| y | number | Yes | Y coordinate of the target point. The value is a floating point number.| 207 208**Error codes** 209 210For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 211 212| ID| Error Message| 213| ------- | --------------------------------------------| 214| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 215 216**Example** 217 218```ts 219import { drawing } from '@kit.ArkGraphics2D'; 220let path = new drawing.Path(); 221path.moveTo(10,10); 222path.lineTo(10, 15); 223``` 224 225### arcTo 226 227arcTo(x1: number, y1: number, x2: number, y2: number, startDeg: number, sweepDeg: number): void 228 229Draws an arc to this path. This is done by using angle arc mode. In this mode, a rectangle that encloses an ellipse is specified first, and then a start angle and a sweep angle are specified. The arc is a portion of the ellipse defined by the start angle and the sweep angle. By default, a line segment from the last point of the path to the start point of the arc is also added. 230 231**System capability**: SystemCapability.Graphics.Drawing 232 233**Parameters** 234 235| Name | Type | Mandatory| Description | 236| -------- | ------ | ---- | -------------------------- | 237| x1 | number | Yes | X coordinate of the upper left corner of the rectangle. The value is a floating point number.| 238| y1 | number | Yes | Y coordinate of the upper left corner of the rectangle. The value is a floating point number.| 239| x2 | number | Yes | X coordinate of the lower right corner of the rectangle. The value is a floating point number.| 240| y2 | number | Yes | Y coordinate of the lower right corner of the rectangle. The value is a floating point number.| 241| startDeg | number | Yes | Start angle, in degrees. The value is a floating point number.| 242| sweepDeg | number | Yes | Sweep degree. The value is a floating point number.| 243 244**Error codes** 245 246For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 247 248| ID| Error Message| 249| ------- | --------------------------------------------| 250| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 251 252**Example** 253 254```ts 255import { drawing } from '@kit.ArkGraphics2D'; 256let path = new drawing.Path(); 257path.moveTo(10,10); 258path.arcTo(10, 15, 10, 10, 10, 10); 259``` 260 261### quadTo 262 263quadTo(ctrlX: number, ctrlY: number, endX: number, endY: number): void 264 265Draws a quadratic Bezier curve from the last point of this path to the target point. If the path is empty, the start point (0, 0) is used. 266 267**System capability**: SystemCapability.Graphics.Drawing 268 269**Parameters** 270 271| Name| Type | Mandatory| Description | 272| ------ | ------ | ---- | --------------------- | 273| ctrlX | number | Yes | X coordinate of the control point. The value is a floating point number.| 274| ctrlY | number | Yes | Y coordinate of the control point. The value is a floating point number.| 275| endX | number | Yes | X coordinate of the target point. The value is a floating point number.| 276| endY | number | Yes | Y coordinate of the target point. The value is a floating point number.| 277 278**Error codes** 279 280For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 281 282| ID| Error Message| 283| ------- | --------------------------------------------| 284| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 285 286**Example** 287 288```ts 289import { drawing } from '@kit.ArkGraphics2D'; 290let path = new drawing.Path(); 291path.moveTo(10,10); 292path.quadTo(10, 15, 10, 10); 293``` 294 295### conicTo<sup>12+</sup> 296 297conicTo(ctrlX: number, ctrlY: number, endX: number, endY: number, weight: number): void 298 299Draws a conic curve from the last point of this path to the target point. If the path is empty, the start point (0, 0) is used. 300 301**System capability**: SystemCapability.Graphics.Drawing 302 303**Parameters** 304 305| Name| Type | Mandatory| Description | 306| ------ | ------ | ---- | --------------------- | 307| ctrlX | number | Yes | X coordinate of the control point. The value is a floating point number.| 308| ctrlY | number | Yes | Y coordinate of the control point. The value is a floating point number.| 309| endX | number | Yes | X coordinate of the target point. The value is a floating point number.| 310| endY | number | Yes | Y coordinate of the target point. The value is a floating point number.| 311| weight | number | Yes | Weight of the curve, which determines its shape. The larger the value, the closer of the curve to the control point. If the value is less than or equal to 0, this API is equivalent to [lineTo](#lineto), that is, adding a line segment from the last point of the path to the target point. If the value is 1, this API is equivalent to [quadTo](#quadto). The value is a floating point number.| 312 313**Error codes** 314 315For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 316 317| ID| Error Message| 318| ------- | --------------------------------------------| 319| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 320 321**Example** 322 323```ts 324import { drawing } from '@kit.ArkGraphics2D'; 325 326const path = new drawing.Path(); 327path.conicTo(200, 400, 100, 200, 0); 328``` 329 330### cubicTo 331 332cubicTo(ctrlX1: number, ctrlY1: number, ctrlX2: number, ctrlY2: number, endX: number, endY: number): void 333 334Draws a cubic Bezier curve from the last point of this path to the target point. If the path is empty, the start point (0, 0) is used. 335 336**System capability**: SystemCapability.Graphics.Drawing 337 338**Parameters** 339 340| Name| Type | Mandatory| Description | 341| ------ | ------ | ---- | --------------------------- | 342| ctrlX1 | number | Yes | X coordinate of the first control point. The value is a floating point number.| 343| ctrlY1 | number | Yes | Y coordinate of the first control point. The value is a floating point number.| 344| ctrlX2 | number | Yes | X coordinate of the second control point. The value is a floating point number.| 345| ctrlY2 | number | Yes | Y coordinate of the second control point. The value is a floating point number.| 346| endX | number | Yes | X coordinate of the target point. The value is a floating point number.| 347| endY | number | Yes | Y coordinate of the target point. The value is a floating point number.| 348 349**Error codes** 350 351For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 352 353| ID| Error Message| 354| ------- | --------------------------------------------| 355| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 356 357**Example** 358 359```ts 360import { drawing } from '@kit.ArkGraphics2D'; 361let path = new drawing.Path(); 362path.moveTo(10,10); 363path.cubicTo(10, 10, 10, 10, 15, 15); 364``` 365 366### rMoveTo<sup>12+</sup> 367 368rMoveTo(dx : number, dy : number): void 369 370Sets the start position relative to the last point of this path. If the path is empty, the start point (0, 0) is used. 371 372**System capability**: SystemCapability.Graphics.Drawing 373 374**Parameters** 375 376| Name| Type | Mandatory| Description | 377| ------ | ------ | ---- | ----------------------- | 378| dx | number | Yes | X offset of the start point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 379| dy | number | Yes | Y offset of the start point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 380 381**Error codes** 382 383For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 384 385| ID| Error Message| 386| ------- | --------------------------------------------| 387| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 388 389**Example** 390 391```ts 392import { drawing } from '@kit.ArkGraphics2D'; 393 394const path = new drawing.Path(); 395path.rMoveTo(10, 10); 396``` 397 398### rLineTo<sup>12+</sup> 399 400rLineTo(dx : number, dy : number): void 401 402Draws a line segment from the last point of this path to a point relative to the last point. If the path is empty, the start point (0, 0) is used. 403 404**System capability**: SystemCapability.Graphics.Drawing 405 406**Parameters** 407 408| Name| Type | Mandatory| Description | 409| ------ | ------ | ---- | ----------------------- | 410| dx | number | Yes | X offset of the target point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 411| dy | number | Yes | Y offset of the target point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 412 413**Error codes** 414 415For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 416 417| ID| Error Message| 418| ------- | --------------------------------------------| 419| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 420 421**Example** 422 423```ts 424import { drawing } from '@kit.ArkGraphics2D'; 425 426const path = new drawing.Path(); 427path.rLineTo(400, 200); 428``` 429 430### rQuadTo<sup>12+</sup> 431 432rQuadTo(dx1: number, dy1: number, dx2: number, dy2: number): void 433 434Draws a quadratic Bezier curve from the last point of this path to a point relative to the last point. If the path is empty, the start point (0, 0) is used. 435 436**System capability**: SystemCapability.Graphics.Drawing 437 438**Parameters** 439 440| Name| Type | Mandatory| Description | 441| ------ | ------ | ---- | --------------------- | 442| dx1 | number | Yes | X offset of the control point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 443| dy1 | number | Yes | Y offset of the control point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 444| dx2 | number | Yes | X offset of the target point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 445| dy2 | number | Yes | Y offset of the target point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 446 447**Error codes** 448 449For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 450 451| ID| Error Message| 452| ------- | --------------------------------------------| 453| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 454 455**Example** 456 457```ts 458import { drawing } from '@kit.ArkGraphics2D'; 459 460const path = new drawing.Path(); 461path.rQuadTo(100, 0, 0, 200); 462``` 463 464### rConicTo<sup>12+</sup> 465 466rConicTo(ctrlX: number, ctrlY: number, endX: number, endY: number, weight: number): void 467 468Draws a conic curve from the last point of this path to a point relative to the last point. If the path is empty, the start point (0, 0) is used. 469 470**System capability**: SystemCapability.Graphics.Drawing 471 472**Parameters** 473 474| Name| Type | Mandatory| Description | 475| ------ | ------ | ---- | --------------------- | 476| ctrlX | number | Yes | X offset of the control point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 477| ctrlY | number | Yes | Y offset of the control point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 478| endX | number | Yes | X offset of the target point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 479| endY | number | Yes | Y offset of the target point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 480| weight | number | Yes | Weight of the curve, which determines its shape. The larger the value, the closer of the curve to the control point. If the value is less than or equal to 0, this API is equivalent to [rLineTo](#rlineto12), that is, adding a line segment from the last point of the path to the target point. If the value is 1, this API is equivalent to [rQuadTo](#rquadto12). The value is a floating point number.| 481 482**Error codes** 483 484For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 485 486| ID| Error Message| 487| ------- | --------------------------------------------| 488| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 489 490**Example** 491 492```ts 493import { drawing } from '@kit.ArkGraphics2D'; 494 495const path = new drawing.Path(); 496path.rConicTo(200, 400, 100, 200, 0); 497``` 498 499### rCubicTo<sup>12+</sup> 500 501rCubicTo(ctrlX1: number, ctrlY1: number, ctrlX2: number, ctrlY2: number, endX: number, endY: number): void 502 503Draws a cubic Bezier curve from the last point of this path to a point relative to the last point. If the path is empty, the start point (0, 0) is used. 504 505**System capability**: SystemCapability.Graphics.Drawing 506 507**Parameters** 508 509| Name| Type | Mandatory| Description | 510| ------ | ------ | ---- | --------------------------- | 511| ctrlX1 | number | Yes | X offset of the first control point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 512| ctrlY1 | number | Yes | Y offset of the first control point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 513| ctrlX2 | number | Yes | X offset of the second control point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 514| ctrlY2 | number | Yes | Y offset of the second control point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 515| endX | number | Yes | X offset of the target point relative to the last point. A positive number indicates a rightward shift from the last point, and a negative number indicates a leftward shift from the last point. The value is a floating point number.| 516| endY | number | Yes | Y offset of the target point relative to the last point. A positive number indicates an upward shift from the last point, and a negative number indicates a downward shift from the last point. The value is a floating point number.| 517 518**Error codes** 519 520For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 521 522| ID| Error Message| 523| ------- | --------------------------------------------| 524| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 525 526**Example** 527 528```ts 529import { drawing } from '@kit.ArkGraphics2D'; 530 531const path = new drawing.Path(); 532path.rCubicTo(200, 0, 0, 200, -20, 0); 533``` 534 535### addArc<sup>12+</sup> 536 537addArc(rect: common2D.Rect, startAngle: number, sweepAngle: number): void 538 539Adds an arc to this path. 540When **startAngle** and **sweepAngle** meet the following conditions, an oval instead of an arc is added: 5411. The result of **startAngle** modulo 90 is close to 0. 5422. The value of **sweepAngle** is not in the range of (-360, 360). 543In other cases, this API adds an arc by applying the result of **sweepAngle** modulo 360 to the path. 544 545**System capability**: SystemCapability.Graphics.Drawing 546 547**Parameters** 548 549| Name | Type | Mandatory | Description | 550| ----------- | ---------------------------------------- | ---- | ------------------- | 551| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangular boundary that encapsulates the oval including the arc. | 552| startAngle | number | Yes | Start angle of the arc, in degrees. The value 0 indicates the positive direction of the X axis. The value is a floating point number.| 553| sweepAngle | number | Yes | Angle to sweep, in degrees. A positive number indicates a clockwise sweep, and a negative number indicates a counterclockwise sweep. The value is a floating point number.| 554 555**Error codes** 556 557For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 558 559| ID| Error Message| 560| ------- | --------------------------------------------| 561| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 562 563**Example** 564 565```ts 566import { common2D, drawing } from '@kit.ArkGraphics2D'; 567 568let path = new drawing.Path(); 569const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 570path.addArc(rect, 90, 180); 571``` 572 573### addCircle<sup>12+</sup> 574 575addCircle(x: number, y: number, radius: number, pathDirection?: PathDirection): void 576 577Adds a circle to this path in the specified direction. The start point of the circle is (x + radius, y). 578 579**System capability**: SystemCapability.Graphics.Drawing 580 581**Parameters** 582 583| Name | Type | Mandatory | Description | 584| ----------- | ---------------------------------------- | ---- | ------------------- | 585| x | number | Yes | X coordinate of the center of the circle. The value is a floating point number.| 586| y | number | Yes | Y coordinate of the center of the circle. The value is a floating point number.| 587| radius | number | Yes | Radius of the circle. The value is a floating point number. If the value is less than or equal to 0, there is no effect.| 588| pathDirection | [PathDirection](#pathdirection12) | No | Direction of the path. The default direction is clockwise.| 589 590**Error codes** 591 592For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 593 594| ID| Error Message| 595| ------- | --------------------------------------------| 596| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 597 598**Example** 599 600```ts 601 602import { drawing } from '@kit.ArkGraphics2D'; 603 604let path = new drawing.Path(); 605path.addCircle(100, 200, 50, drawing.PathDirection.CLOCKWISE); 606``` 607 608### addOval<sup>12+</sup> 609 610addOval(rect: common2D.Rect, start: number, pathDirection?: PathDirection): void 611 612Adds an oval to this path in the specified direction, where the **common2D.Rect** object specifies the outer tangent rectangle of the oval. 613 614**System capability**: SystemCapability.Graphics.Drawing 615 616**Parameters** 617 618| Name | Type | Mandatory | Description | 619| ----------- | ---------------------------------------- | ---- | ------------------- | 620| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangular boundary of the oval. | 621| start | number | Yes | Start point of the oval, where 0, 1, 2, and 3 correspond to the upper, right, lower, and left points, respectively. The value is an integer greater than or equal to 0. If the value is greater than or equal to 4, the remainder of 4 is used.| 622| pathDirection | [PathDirection](#pathdirection12) | No | Direction of the path. The default direction is clockwise.| 623 624**Error codes** 625 626For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 627 628| ID| Error Message| 629| ------- | --------------------------------------------| 630| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 631 632**Example** 633 634```ts 635import { common2D, drawing } from '@kit.ArkGraphics2D'; 636 637let path = new drawing.Path(); 638const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 639path.addOval(rect, 5, drawing.PathDirection.CLOCKWISE); 640``` 641 642### addRect<sup>12+</sup> 643 644addRect(rect: common2D.Rect, pathDirection?: PathDirection): void 645 646Adds a rectangle to this path in the specified direction. The start point is the upper left corner of the rectangle. 647 648**System capability**: SystemCapability.Graphics.Drawing 649 650**Parameters** 651 652| Name | Type | Mandatory | Description | 653| ----------- | ---------------------------------------- | ---- | ------------------- | 654| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangle. | 655| pathDirection | [PathDirection](#pathdirection12) | No | Direction of the path. The default direction is clockwise.| 656 657**Error codes** 658 659For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 660 661| ID| Error Message| 662| ------- | --------------------------------------------| 663| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 664 665**Example** 666 667```ts 668import { common2D, drawing } from '@kit.ArkGraphics2D'; 669 670let path = new drawing.Path(); 671const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 672path.addRect(rect, drawing.PathDirection.CLOCKWISE); 673``` 674 675### addRoundRect<sup>12+</sup> 676 677addRoundRect(roundRect: RoundRect, pathDirection?: PathDirection): void 678 679Adds a rounded rectangle to this path in the specified direction. When the path direction is clockwise, the start point is at the intersection of the rounded rectangle's left boundary and its lower left corner. When the path direction is counterclockwise, the start point is at the intersection point between the left boundary and the upper left corner. 680 681**System capability**: SystemCapability.Graphics.Drawing 682 683**Parameters** 684 685| Name | Type | Mandatory | Description | 686| ----------- | ---------------------------------------- | ---- | ------------------- | 687| roundRect | [RoundRect](#roundrect12) | Yes | Rounded rectangle. | 688| pathDirection | [PathDirection](#pathdirection12) | No | Direction of the path. The default direction is clockwise.| 689 690**Error codes** 691 692For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 693 694| ID| Error Message| 695| ------- | --------------------------------------------| 696| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 697 698**Example** 699 700```ts 701import { common2D, drawing } from '@kit.ArkGraphics2D'; 702 703let path = new drawing.Path(); 704const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 705let roundRect = new drawing.RoundRect(rect, 50, 50); 706path.addRoundRect(roundRect, drawing.PathDirection.CLOCKWISE); 707``` 708 709### addPath<sup>12+</sup> 710 711addPath(path: Path, matrix?: Matrix | null): void 712 713Transforms the points in a path by a matrix and stores the resulting path in the current **Path** object. 714 715**System capability**: SystemCapability.Graphics.Drawing 716 717**Parameters** 718 719| Name | Type | Mandatory | Description | 720| ----------- | ---------------------------------------- | ---- | ------------------- | 721| path | [Path](#path) | Yes | Source **Path** object. | 722| matrix | [Matrix](#matrix12)\|null | No | **Matrix** object. The default value is an identity matrix.| 723 724**Error codes** 725 726For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 727 728| ID| Error Message| 729| ------- | --------------------------------------------| 730| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 731 732**Example** 733 734```ts 735import { common2D, drawing } from '@kit.ArkGraphics2D'; 736 737let path = new drawing.Path(); 738let matrix = new drawing.Matrix(); 739const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 740let roundRect = new drawing.RoundRect(rect, 50, 50); 741path.addRoundRect(roundRect, drawing.PathDirection.CLOCKWISE); 742let dstPath = new drawing.Path(); 743dstPath.addPath(path, matrix); 744``` 745 746### transform<sup>12+</sup> 747 748transform(matrix: Matrix): void 749 750Transforms the points in this path by a matrix. 751 752**System capability**: SystemCapability.Graphics.Drawing 753 754**Parameters** 755 756| Name | Type | Mandatory | Description | 757| ----------- | ---------------------------------------- | ---- | ------------------- | 758| matrix | [Matrix](#matrix12) | Yes | **Matrix** object.| 759 760**Error codes** 761 762For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 763 764| ID| Error Message| 765| ------- | --------------------------------------------| 766| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 767 768**Example** 769 770```ts 771import { common2D, drawing } from '@kit.ArkGraphics2D'; 772 773let path = new drawing.Path(); 774let matrix = new drawing.Matrix(); 775matrix.setScale(1.5, 1.5, 10, 10); 776const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 777let roundRect = new drawing.RoundRect(rect, 50, 50); 778path.addRoundRect(roundRect, drawing.PathDirection.CLOCKWISE); 779path.transform(matrix); 780``` 781 782### contains<sup>12+</sup> 783 784contains(x: number, y: number): boolean 785 786Checks whether a coordinate point is included in this path. For details, see [PathFillType](#pathfilltype12). 787 788**System capability**: SystemCapability.Graphics.Drawing 789 790**Parameters** 791 792| Name| Type | Mandatory| Description | 793| ------ | ------ | ---- | ----------------------- | 794| x | number | Yes | X coordinate. The value is a floating point number.| 795| y | number | Yes | Y coordinate. The value is a floating point number.| 796 797**Return value** 798 799| Type | Description | 800| ------- | -------------- | 801| boolean | Result indicating whether the coordinate point is included in the path. The value **true** means that the coordinate point is included in the path, and **false** means the opposite.| 802 803**Error codes** 804 805For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 806 807| ID| Error Message| 808| ------- | --------------------------------------------| 809| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 810 811**Example** 812 813```ts 814import { common2D, drawing } from '@kit.ArkGraphics2D'; 815 816const path = new drawing.Path(); 817let rect : common2D.Rect = {left: 50, top: 50, right: 250, bottom: 250}; 818path.addRect(rect, drawing.PathDirection.CLOCKWISE); 819console.info("test contains: " + path.contains(0, 0)); 820console.info("test contains: " + path.contains(60, 60)); 821``` 822 823### setFillType<sup>12+</sup> 824 825setFillType(pathFillType: PathFillType): void 826 827Sets the fill type of this path. The fill type determines how "inside" of the path is drawn. For example, when the fill type **Winding** is used, "inside" of the path is determined by a non-zero sum of signed edge crossings. When **EvenOdd** is used, "inside" of the path is determined by an odd number of edge crossings. 828 829**System capability**: SystemCapability.Graphics.Drawing 830 831**Parameters** 832 833| Name | Type | Mandatory | Description | 834| ----------- | ---------------------------------------- | ---- | ------------------- | 835| pathFillType | [PathFillType](#pathfilltype12) | Yes | Fill type of the path.| 836 837**Error codes** 838 839For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 840 841| ID| Error Message| 842| ------- | --------------------------------------------| 843| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 844 845**Example** 846 847```ts 848import { drawing } from '@kit.ArkGraphics2D'; 849 850const path = new drawing.Path(); 851path.setFillType(drawing.PathFillType.WINDING); 852``` 853 854### getBounds<sup>12+</sup> 855 856getBounds(): common2D.Rect 857 858Obtains the minimum bounding rectangle that encloses this path. 859 860**System capability**: SystemCapability.Graphics.Drawing 861 862**Return value** 863 864| Type | Description | 865| -------------------------------------------------- | ---------------------- | 866| [common2D.Rect](js-apis-graphics-common2D.md#rect) | Minimum bounding rectangle.| 867 868**Example** 869 870```ts 871import { common2D, drawing } from '@kit.ArkGraphics2D'; 872 873const path = new drawing.Path(); 874path.lineTo(50, 40) 875let rect : common2D.Rect = {left: 0, top: 0, right: 0, bottom: 0}; 876rect = path.getBounds(); 877console.info("test rect.left: " + rect.left); 878console.info("test rect.top: " + rect.top); 879console.info("test rect.right: " + rect.right); 880console.info("test rect.bottom: " + rect.bottom); 881``` 882 883### addPolygon<sup>12+</sup> 884 885addPolygon(points: Array\<common2D.Point>, close: boolean): void 886 887Adds a polygon to this path. 888 889**System capability**: SystemCapability.Graphics.Drawing 890 891**Parameters** 892 893| Name| Type | Mandatory| Description | 894| ------ | ------ | ---- | ----------------------- | 895| points | Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Yes | Array that holds the vertex coordinates of the polygon.| 896| close | boolean | Yes | Whether to close the path, that is, whether to add a line segment from the start point to the end point of the path. The value **true** means to close the path, and **false** means the opposite.| 897 898**Error codes** 899 900For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 901 902| ID| Error Message| 903| ------- | --------------------------------------------| 904| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 905 906**Example** 907 908```ts 909import { common2D, drawing } from '@kit.ArkGraphics2D'; 910 911let pointsArray = new Array<common2D.Point>(); 912const point1: common2D.Point = { x: 200, y: 200 }; 913const point2: common2D.Point = { x: 400, y: 200 }; 914const point3: common2D.Point = { x: 100, y: 400 }; 915const point4: common2D.Point = { x: 300, y: 400 }; 916pointsArray.push(point1); 917pointsArray.push(point2); 918pointsArray.push(point3); 919pointsArray.push(point4); 920const path = new drawing.Path(); 921path.addPolygon(pointsArray, false); 922``` 923 924### offset<sup>12+</sup> 925 926offset(dx: number, dy: number): Path 927 928Offsets this path by specified distances along the X axis and Y axis and stores the resulting path in the **Path** object returned. 929 930**System capability**: SystemCapability.Graphics.Drawing 931 932**Parameters** 933 934| Name| Type | Mandatory| Description | 935| ------ | ------ | ---- | ----------------------- | 936| dx | number | Yes | X offset. A positive number indicates an offset towards the positive direction of the X axis, and a negative number indicates an offset towards the negative direction of the X axis. The value is a floating point number.| 937| dy | number | Yes | Y offset. A positive number indicates an offset towards the positive direction of the Y axis, and a negative number indicates an offset towards the negative direction of the Y axis. The value is a floating point number.| 938 939**Return value** 940 941| Type | Description | 942| ------ | ------------------ | 943| [Path](#path) | New path generated.| 944 945**Error codes** 946 947For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 948 949| ID| Error Message| 950| ------- | --------------------------------------------| 951| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 952 953**Example** 954 955```ts 956import { drawing } from '@kit.ArkGraphics2D'; 957 958const path = new drawing.Path(); 959path.moveTo(200, 200); 960path.lineTo(300, 300); 961const dst = path.offset(200, 200); 962``` 963 964### op<sup>12+</sup> 965 966op(path: Path, pathOp: PathOp): boolean 967 968Combines this path with the passed-in path based on the specified operation mode. 969 970**System capability**: SystemCapability.Graphics.Drawing 971 972**Parameters** 973 974| Name| Type | Mandatory| Description | 975| ------ | ------ | ---- | ----------------------- | 976| path | [Path](#path) | Yes | Path object, which will be combined with the current path.| 977| pathOp | [PathOp](#pathop12) | Yes | Operation mode. | 978 979**Return value** 980 981| Type | Description | 982| ------ | ------------------ | 983| boolean | Result of the path combination result. The value **true** means that the path combination is successful, and **false** means the opposite.| 984 985**Error codes** 986 987For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 988 989| ID| Error Message| 990| ------- | --------------------------------------------| 991| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 992 993**Example** 994 995```ts 996import { drawing } from '@kit.ArkGraphics2D'; 997 998const path = new drawing.Path(); 999const path2 = new drawing.Path(); 1000path.addCircle(100, 200, 100, drawing.PathDirection.CLOCKWISE); 1001console.info("get pathOp: ", path2.op(path, drawing.PathOp.DIFFERENCE)); 1002``` 1003 1004### close 1005 1006close(): void 1007 1008Draws a line segment from the current point to the start point of this path. 1009 1010**System capability**: SystemCapability.Graphics.Drawing 1011 1012**Example** 1013 1014```ts 1015import { drawing } from '@kit.ArkGraphics2D'; 1016let path = new drawing.Path(); 1017path.moveTo(10,10); 1018path.cubicTo(10, 10, 10, 10, 15, 15); 1019path.close(); 1020``` 1021 1022### reset 1023 1024reset(): void 1025 1026Resets the path data. 1027 1028**System capability**: SystemCapability.Graphics.Drawing 1029 1030**Example** 1031 1032```ts 1033import { drawing } from '@kit.ArkGraphics2D'; 1034let path = new drawing.Path(); 1035path.moveTo(10,10); 1036path.cubicTo(10, 10, 10, 10, 15, 15); 1037path.reset(); 1038``` 1039 1040### getLength<sup>12+</sup> 1041 1042getLength(forceClosed: boolean): number 1043 1044Obtains the path length. 1045 1046**System capability**: SystemCapability.Graphics.Drawing 1047 1048**Parameters** 1049 1050| Name| Type | Mandatory| Description | 1051| ----- | ------ | ---- | --------- | 1052| forceClosed | boolean | Yes | Whether the path is measured as a closed path. The value **true** means that the path is considered closed during measurement, and **false** means that the path is measured based on the actual closed status.| 1053 1054**Return value** 1055 1056| Type | Description| 1057| ------ | ---- | 1058| number | Path length.| 1059 1060**Example** 1061 1062```ts 1063import { drawing } from '@kit.ArkGraphics2D' 1064let path = new drawing.Path(); 1065path.arcTo(20, 20, 180, 180, 180, 90); 1066let len = path.getLength(false); 1067console.info("path length = " + len); 1068``` 1069 1070### getPositionAndTangent<sup>12+</sup> 1071 1072getPositionAndTangent(forceClosed: boolean, distance: number, position: common2D.Point, tangent: common2D.Point): boolean 1073 1074Obtains the coordinates and tangent at a distance from the start point of this path. 1075 1076**System capability**: SystemCapability.Graphics.Drawing 1077 1078**Parameters** 1079 1080| Name | Type | Mandatory| Description | 1081| -------- | -------------------------------------------- | ---- | ------------------------------- | 1082| forceClosed | boolean | Yes | Whether the path is measured as a closed path. The value **true** means that the path is considered closed during measurement, and **false** means that the path is measured based on the actual closed status. | 1083| distance | number | Yes | Distance from the start point. If a negative number is passed in, the value **0** is used. If a value greater than the path length is passed in, the path length is used. The value is a floating point number. | 1084| position | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Coordinates obtained. | 1085| tangent | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Tangent obtained, where **tangent.x** and **tangent.y** represent the cosine and sine of the tangent of the point, respectively. | 1086 1087**Return value** 1088 1089| Type | Description | 1090| --------------------- | -------------- | 1091| boolean |Result indicating whether the coordinates and tangent of the point are obtained. The value **true** means that they are obtained, and **false** means the opposite. The values of **position** and **tangent** are not changed.| 1092 1093**Error codes** 1094 1095For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1096 1097| ID| Error Message| 1098| ------- | --------------------------------------------| 1099| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1100 1101**Example** 1102 1103```ts 1104import { common2D, drawing } from '@kit.ArkGraphics2D'; 1105let path: drawing.Path = new drawing.Path(); 1106path.moveTo(0, 0); 1107path.lineTo(0, 700); 1108path.lineTo(700, 0); 1109let position: common2D.Point = { x: 0.0, y: 0.0 }; 1110let tangent: common2D.Point = { x: 0.0, y: 0.0 }; 1111if (path.getPositionAndTangent(false, 0.1, position, tangent)) { 1112 console.info("getPositionAndTangent-----position: "+ position.x); 1113 console.info("getPositionAndTangent-----position: "+ position.y); 1114 console.info("getPositionAndTangent-----tangent: "+ tangent.x); 1115 console.info("getPositionAndTangent-----tangent: "+ tangent.y); 1116} 1117``` 1118 1119### isClosed<sup>12+</sup> 1120 1121isClosed(): boolean 1122 1123Checks whether a path is closed. 1124 1125**System capability**: SystemCapability.Graphics.Drawing 1126 1127**Return value** 1128 1129| Type | Description | 1130| --------------------- | -------------- | 1131| boolean | Result indicating whether the path is closed. The value **true** means that the path is closed, and **false** means the opposite.| 1132 1133**Example** 1134 1135```ts 1136import { drawing } from '@kit.ArkGraphics2D'; 1137let path: drawing.Path = new drawing.Path(); 1138path.moveTo(0, 0); 1139path.lineTo(0, 700); 1140if (path.isClosed()) { 1141 console.info("path is closed."); 1142} else { 1143 console.info("path is not closed."); 1144} 1145``` 1146 1147### getMatrix<sup>12+</sup> 1148 1149getMatrix(forceClosed: boolean, distance: number, matrix: Matrix, flags: PathMeasureMatrixFlags): boolean 1150 1151Obtains a transformation matrix at a distance from the start point of this path. 1152 1153**System capability**: SystemCapability.Graphics.Drawing 1154 1155**Parameters** 1156 1157| Name | Type | Mandatory| Description | 1158| -------- | -------------------------------------------- | ---- | ------------------------------- | 1159| forceClosed | boolean | Yes | Whether the path is measured as a closed path. The value **true** means that the path is considered closed during measurement, and **false** means that the path is measured based on the actual closed status. | 1160| distance | number | Yes | Distance from the start point. If a negative number is passed in, the value **0** is used. If a value greater than the path length is passed in, the path length is used. The value is a floating point number. | 1161| matrix | [Matrix](#matrix12) | Yes | **Matrix** object used to store the matrix obtained. | 1162| flags | [PathMeasureMatrixFlags](#pathmeasurematrixflags12) | Yes | Type of the matrix information obtained. | 1163 1164**Return value** 1165 1166| Type | Description | 1167| --------------------- | -------------- | 1168| boolean | Result indicating whether a transformation matrix is obtained. The value **true** means that a transformation matrix is obtained, and **false** means the opposite.| 1169 1170**Error codes** 1171 1172For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1173 1174| ID| Error Message| 1175| ------- | --------------------------------------------| 1176| 401 | Parameter error. Possible causes: Mandatory parameters are left unspecified. | 1177 1178**Example** 1179 1180```ts 1181import { drawing } from '@kit.ArkGraphics2D'; 1182let path: drawing.Path = new drawing.Path(); 1183let matrix = new drawing.Matrix(); 1184if(path.getMatrix(false, 10, matrix, drawing.PathMeasureMatrixFlags.GET_TANGENT_MATRIX)) { 1185 console.info("path.getMatrix return true"); 1186} else { 1187 console.info("path.getMatrix return false"); 1188} 1189``` 1190 1191### buildFromSvgString<sup>12+</sup> 1192 1193buildFromSvgString(str: string): boolean 1194 1195Parses the path represented by an SVG string. 1196 1197**System capability**: SystemCapability.Graphics.Drawing 1198 1199**Parameters** 1200 1201| Name | Type | Mandatory| Description | 1202| -------- | -------------------------------------------- | ---- | ------------------------------- | 1203| str | string | Yes | String in SVG format, which is used to describe the path. | 1204 1205**Return value** 1206 1207| Type | Description | 1208| --------------------- | -------------- | 1209| boolean | Result indicating whether the SVG string is parsed. The value **true** means that the parsing is successful, and **false** means the opposite.| 1210 1211**Error codes** 1212 1213For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1214 1215| ID| Error Message| 1216| ------- | --------------------------------------------| 1217| 401 | Parameter error. Possible causes: Mandatory parameters are left unspecified. | 1218 1219**Example** 1220 1221```ts 1222import { drawing } from '@kit.ArkGraphics2D'; 1223let path: drawing.Path = new drawing.Path(); 1224let svgStr: string = "M150 100 L75 300 L225 300 Z"; 1225if(path.buildFromSvgString(svgStr)) { 1226 console.info("buildFromSvgString return true"); 1227} else { 1228 console.info("buildFromSvgString return false"); 1229} 1230``` 1231 1232## Canvas 1233 1234A carrier that carries the drawn content and drawing status. 1235 1236> **NOTE** 1237> 1238> By default, the canvas has a black brush with anti-aliasing enabled but no any other style. This default brush takes effect only when no brush or pen is proactively set in the canvas. 1239 1240### constructor 1241 1242constructor(pixelmap: image.PixelMap) 1243 1244A constructor used to create a **Canvas** object. 1245 1246**System capability**: SystemCapability.Graphics.Drawing 1247 1248**Parameters** 1249 1250| Name | Type | Mandatory| Description | 1251| -------- | -------------------------------------------- | ---- | -------------- | 1252| pixelmap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map used to create the object.| 1253 1254**Error codes** 1255 1256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1257 1258| ID| Error Message| 1259| ------- | --------------------------------------------| 1260| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1261 1262**Example** 1263 1264```ts 1265import { drawing } from '@kit.ArkGraphics2D'; 1266import { image } from '@kit.ImageKit'; 1267const color = new ArrayBuffer(96); 1268let opts : image.InitializationOptions = { 1269 editable: true, 1270 pixelFormat: 3, 1271 size: { 1272 height: 4, 1273 width: 6 1274 } 1275} 1276image.createPixelMap(color, opts).then((pixelMap) => { 1277 const canvas = new drawing.Canvas(pixelMap); 1278}) 1279``` 1280 1281### drawRect 1282 1283drawRect(rect: common2D.Rect): void 1284 1285Draws a rectangle. By default, black is used for filling. 1286 1287**System capability**: SystemCapability.Graphics.Drawing 1288 1289**Parameters** 1290 1291| Name| Type | Mandatory| Description | 1292| ------ | -------------------------------------------------- | ---- | -------------- | 1293| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangle to draw.| 1294 1295**Error codes** 1296 1297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1298 1299| ID| Error Message| 1300| ------- | --------------------------------------------| 1301| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1302 1303**Example** 1304 1305```ts 1306import { RenderNode } from '@kit.ArkUI'; 1307import { common2D, drawing } from '@kit.ArkGraphics2D'; 1308class DrawingRenderNode extends RenderNode { 1309 draw(context : DrawContext) { 1310 const canvas = context.canvas; 1311 const pen = new drawing.Pen(); 1312 pen.setStrokeWidth(5); 1313 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 1314 canvas.attachPen(pen); 1315 canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 }); 1316 canvas.detachPen(); 1317 } 1318} 1319``` 1320 1321### drawRect<sup>12+</sup> 1322 1323drawRect(left: number, top: number, right: number, bottom: number): void 1324 1325Draws a rectangle. By default, black is used for filling. This API provides better performance than [drawRect](#drawrect) and is recommended. 1326 1327**System capability**: SystemCapability.Graphics.Drawing 1328 1329**Parameters** 1330 1331| Name| Type | Mandatory| Description | 1332| ------ | ------ | ---- | -------------- | 1333| left | number | Yes | X coordinate of the upper left corner of the rectangle. The value is a floating point number.| 1334| top | number | Yes | Y coordinate of the upper left corner of the rectangle. The value is a floating point number.| 1335| right | number | Yes | X coordinate of the lower right corner of the rectangle. The value is a floating point number.| 1336| bottom | number | Yes | Y coordinate of the lower right corner of the rectangle. The value is a floating point number.| 1337 1338**Error codes** 1339 1340For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1341 1342| ID| Error Message| 1343| ------- | --------------------------------------------| 1344| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1345 1346**Example** 1347 1348```ts 1349import { RenderNode } from '@kit.ArkUI'; 1350import { drawing } from '@kit.ArkGraphics2D'; 1351class DrawingRenderNode extends RenderNode { 1352 1353 draw(context : DrawContext) { 1354 const canvas = context.canvas; 1355 const pen = new drawing.Pen(); 1356 pen.setStrokeWidth(5); 1357 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 1358 canvas.attachPen(pen); 1359 canvas.drawRect(0, 0, 10, 10); 1360 canvas.detachPen(); 1361 } 1362} 1363``` 1364 1365### drawRoundRect<sup>12+</sup> 1366 1367drawRoundRect(roundRect: RoundRect): void 1368 1369Draws a rounded rectangle. 1370 1371**System capability**: SystemCapability.Graphics.Drawing 1372 1373**Parameters** 1374 1375| Name | Type | Mandatory| Description | 1376| ---------- | ----------------------- | ---- | ------------ | 1377| roundRect | [RoundRect](#roundrect12) | Yes | Rounded rectangle.| 1378 1379**Error codes** 1380 1381For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1382 1383| ID| Error Message| 1384| ------- | --------------------------------------------| 1385| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1386 1387**Example** 1388 1389```ts 1390import { RenderNode } from '@kit.ArkUI'; 1391import { common2D, drawing } from '@kit.ArkGraphics2D'; 1392class DrawingRenderNode extends RenderNode { 1393 draw(context : DrawContext) { 1394 const canvas = context.canvas; 1395 let rect: common2D.Rect = { left : 100, top : 100, right : 400, bottom : 500 }; 1396 let roundRect = new drawing.RoundRect(rect, 10, 10); 1397 canvas.drawRoundRect(roundRect); 1398 } 1399} 1400``` 1401 1402### drawNestedRoundRect<sup>12+</sup> 1403 1404drawNestedRoundRect(outer: RoundRect, inner: RoundRect): void 1405 1406Draws two nested rounded rectangles. The outer rectangle boundary must contain the inner rectangle boundary. Otherwise, there is no drawing effect. 1407 1408**System capability**: SystemCapability.Graphics.Drawing 1409 1410**Parameters** 1411 1412| Name | Type | Mandatory| Description | 1413| ------ | ----------------------- | ---- | ------------ | 1414| outer | [RoundRect](#roundrect12) | Yes | Outer rounded rectangle.| 1415| inner | [RoundRect](#roundrect12) | Yes | Inner rounded rectangle.| 1416 1417**Error codes** 1418 1419For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1420 1421| ID| Error Message| 1422| ------- | --------------------------------------------| 1423| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1424 1425**Example** 1426 1427```ts 1428import { RenderNode } from '@kit.ArkUI'; 1429import { common2D, drawing } from '@kit.ArkGraphics2D'; 1430class DrawingRenderNode extends RenderNode { 1431 draw(context : DrawContext) { 1432 const canvas = context.canvas; 1433 let inRect: common2D.Rect = { left : 200, top : 200, right : 400, bottom : 500 }; 1434 let outRect: common2D.Rect = { left : 100, top : 100, right : 400, bottom : 500 }; 1435 let outRoundRect = new drawing.RoundRect(outRect, 10, 10); 1436 let inRoundRect = new drawing.RoundRect(inRect, 10, 10); 1437 canvas.drawNestedRoundRect(outRoundRect, inRoundRect); 1438 canvas.drawRoundRect(outRoundRect); 1439 } 1440} 1441``` 1442 1443### drawBackground<sup>12+</sup> 1444 1445drawBackground(brush: Brush): void 1446 1447Uses a brush to fill the drawable area of the canvas. 1448 1449**System capability**: SystemCapability.Graphics.Drawing 1450 1451**Parameters** 1452 1453| Name| Type | Mandatory| Description | 1454| ------ | --------------- | ---- | ---------- | 1455| brush | [Brush](#brush) | Yes | **Brush** object.| 1456 1457**Error codes** 1458 1459For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1460 1461| ID| Error Message| 1462| ------- | --------------------------------------------| 1463| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1464 1465**Example** 1466 1467```ts 1468import { RenderNode } from '@kit.ArkUI'; 1469import { common2D, drawing } from '@kit.ArkGraphics2D'; 1470class DrawingRenderNode extends RenderNode { 1471 draw(context : DrawContext) { 1472 const canvas = context.canvas; 1473 const brush = new drawing.Brush(); 1474 const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 1475 brush.setColor(color); 1476 canvas.drawBackground(brush); 1477 } 1478} 1479``` 1480 1481### drawShadow<sup>12+</sup> 1482 1483drawShadow(path: Path, planeParams: common2D.Point3d, devLightPos: common2D.Point3d, lightRadius: number, ambientColor: common2D.Color, spotColor: common2D.Color, flag: ShadowFlag) : void 1484 1485Draws a spot shadow and uses a given path to outline the ambient shadow. 1486 1487**System capability**: SystemCapability.Graphics.Drawing 1488 1489**Parameters** 1490 1491| Name | Type | Mandatory | Description | 1492| ------------ | ---------------------------------------- | ---- | ---------- | 1493| path | [Path](#path) | Yes | **Path** object, which is used to outline the shadow.| 1494| planeParams | [common2D.Point3d](js-apis-graphics-common2D.md#point3d12) | Yes | 3D vector, which is used to calculate the offset in the Z axis.| 1495| devLightPos | [common2D.Point3d](js-apis-graphics-common2D.md#point3d12) | Yes | Position of the light relative to the canvas.| 1496| lightRadius | number | Yes | Radius of the light. The value is a floating point number. | 1497| ambientColor | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color of the ambient shadow.| 1498| spotColor | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color of the spot shadow.| 1499| flag | [ShadowFlag](#shadowflag12) | Yes | Shadow flag. | 1500 1501**Error codes** 1502 1503For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1504 1505| ID| Error Message| 1506| ------- | --------------------------------------------| 1507| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 1508 1509**Example** 1510 1511```ts 1512import { RenderNode } from '@kit.ArkUI'; 1513import { common2D, drawing } from '@kit.ArkGraphics2D'; 1514class DrawingRenderNode extends RenderNode { 1515 draw(context : DrawContext) { 1516 const canvas = context.canvas; 1517 const path = new drawing.Path(); 1518 path.addCircle(100, 200, 100, drawing.PathDirection.CLOCKWISE); 1519 let pen = new drawing.Pen(); 1520 pen.setAntiAlias(true); 1521 let pen_color : common2D.Color = { alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 }; 1522 pen.setColor(pen_color); 1523 pen.setStrokeWidth(10.0); 1524 canvas.attachPen(pen); 1525 let brush = new drawing.Brush(); 1526 let brush_color : common2D.Color = { alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00 }; 1527 brush.setColor(brush_color); 1528 canvas.attachBrush(brush); 1529 let point1 : common2D.Point3d = {x: 100, y: 80, z:80}; 1530 let point2 : common2D.Point3d = {x: 200, y: 10, z:40}; 1531 let color1 : common2D.Color = {alpha: 0xFF, red:0, green:0, blue:0xFF}; 1532 let color2 : common2D.Color = {alpha: 0xFF, red:0xFF, green:0, blue:0}; 1533 let shadowFlag : drawing.ShadowFlag = drawing.ShadowFlag.ALL; 1534 canvas.drawShadow(path, point1, point2, 30, color1, color2, shadowFlag); 1535 } 1536} 1537``` 1538 1539### getLocalClipBounds<sup>12+</sup> 1540 1541getLocalClipBounds(): common2D.Rect 1542 1543Obtains the bounds of the cropping region of the canvas. 1544 1545**System capability**: SystemCapability.Graphics.Drawing 1546 1547**Return value** 1548 1549| Type | Description | 1550| ---------------------------------------- | -------- | 1551| [common2D.Rect](js-apis-graphics-common2D.md#rect) | Bounds of the cropping region.| 1552 1553**Example** 1554 1555```ts 1556import { RenderNode } from '@kit.ArkUI'; 1557import { common2D, drawing } from '@kit.ArkGraphics2D'; 1558class DrawingRenderNode extends RenderNode { 1559 draw(context : DrawContext) { 1560 const canvas = context.canvas; 1561 let clipRect: common2D.Rect = { 1562 left : 150, top : 150, right : 300, bottom : 400 1563 }; 1564 canvas.clipRect(clipRect,drawing.ClipOp.DIFFERENCE, true); 1565 console.info("test rect.left: " + clipRect.left); 1566 console.info("test rect.top: " + clipRect.top); 1567 console.info("test rect.right: " + clipRect.right); 1568 console.info("test rect.bottom: " + clipRect.bottom); 1569 canvas.getLocalClipBounds(); 1570 } 1571} 1572``` 1573 1574### getTotalMatrix<sup>12+</sup> 1575 1576getTotalMatrix(): Matrix 1577 1578Obtains the canvas matrix. 1579 1580**System capability**: SystemCapability.Graphics.Drawing 1581 1582**Return value** 1583 1584| Type | Description | 1585| ----------------- | -------- | 1586| [Matrix](#matrix12) |Canvas matrix.| 1587 1588**Example** 1589 1590```ts 1591import { RenderNode } from '@kit.ArkUI'; 1592import { drawing } from '@kit.ArkGraphics2D'; 1593class DrawingRenderNode extends RenderNode { 1594 draw(context : DrawContext) { 1595 const canvas = context.canvas; 1596 let matrix = new drawing.Matrix(); 1597 matrix.setMatrix([5, 0, 0, 0, 1, 1, 0, 0, 1]); 1598 canvas.setMatrix(matrix); 1599 let matrixResult =canvas.getTotalMatrix(); 1600 } 1601} 1602``` 1603 1604### drawCircle 1605 1606drawCircle(x: number, y: number, radius: number): void 1607 1608Draws a circle. If the radius is less than or equal to zero, nothing is drawn. By default, black is used for filling. 1609 1610**System capability**: SystemCapability.Graphics.Drawing 1611 1612**Parameters** 1613 1614| Name| Type | Mandatory| Description | 1615| ------ | ------ | ---- | ------------------- | 1616| x | number | Yes | X coordinate of the center of the circle. The value is a floating point number.| 1617| y | number | Yes | Y coordinate of the center of the circle. The value is a floating point number.| 1618| radius | number | Yes | Radius of the circle. The value is a floating point number greater than 0.| 1619 1620**Error codes** 1621 1622For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1623 1624| ID| Error Message| 1625| ------- | --------------------------------------------| 1626| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 1627 1628**Example** 1629 1630```ts 1631import { RenderNode } from '@kit.ArkUI'; 1632import { drawing } from '@kit.ArkGraphics2D'; 1633class DrawingRenderNode extends RenderNode { 1634 draw(context : DrawContext) { 1635 const canvas = context.canvas; 1636 const pen = new drawing.Pen(); 1637 pen.setStrokeWidth(5); 1638 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 1639 canvas.attachPen(pen); 1640 canvas.drawCircle(10, 10, 2); 1641 canvas.detachPen(); 1642 } 1643} 1644``` 1645 1646### drawImage 1647 1648drawImage(pixelmap: image.PixelMap, left: number, top: number, samplingOptions?: SamplingOptions): void 1649 1650Draws an image. The coordinates of the upper left corner of the image are (left, top). 1651 1652**System capability**: SystemCapability.Graphics.Drawing 1653 1654**Parameters** 1655 1656| Name | Type | Mandatory| Description | 1657| -------- | -------------------------------------------- | ---- | ------------------------------- | 1658| pixelmap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map of the image. | 1659| left | number | Yes | X coordinate of the upper left corner of the image. The value is a floating point number.| 1660| top | number | Yes | Y coordinate of the upper left corner of the image. The value is a floating point number.| 1661| samplingOptions<sup>12+</sup> | [SamplingOptions](#samplingoptions12) | No | Sampling options. By default, the **SamplingOptions** object created using the no-argument constructor is used.| 1662 1663**Error codes** 1664 1665For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1666 1667| ID| Error Message| 1668| ------- | --------------------------------------------| 1669| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1670 1671**Example** 1672 1673```ts 1674import { RenderNode } from '@kit.ArkUI'; 1675import { image } from '@kit.ImageKit'; 1676import { drawing } from '@kit.ArkGraphics2D'; 1677class DrawingRenderNode extends RenderNode { 1678 pixelMap: image.PixelMap | null = null; 1679 1680 async draw(context : DrawContext) { 1681 const canvas = context.canvas; 1682 let options = new drawing.SamplingOptions(drawing.FilterMode.FILTER_MODE_NEAREST); 1683 if (this.pixelMap != null) { 1684 canvas.drawImage(this.pixelMap, 0, 0, options); 1685 } 1686 } 1687} 1688``` 1689 1690### drawImageRect<sup>12+</sup> 1691 1692drawImageRect(pixelmap: image.PixelMap, dstRect: common2D.Rect, samplingOptions?: SamplingOptions): void 1693 1694Draws an image onto a specified area of the canvas. 1695 1696**System capability**: SystemCapability.Graphics.Drawing 1697 1698**Parameters** 1699 1700| Name | Type | Mandatory| Description | 1701| -------- | -------------------------------------------- | ---- | ------------------------------- | 1702| pixelmap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map of the image. | 1703| dstRect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | **Rectangle** object, which specifies the area of the canvas onto which the image will be drawn.| 1704| samplingOptions | [SamplingOptions](#samplingoptions12) | No | Sampling options. By default, the **SamplingOptions** object created using the no-argument constructor is used.| 1705 1706**Error codes** 1707 1708For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1709 1710| ID| Error Message| 1711| ------- | --------------------------------------------| 1712| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1713 1714**Example** 1715 1716```ts 1717import { RenderNode } from '@kit.ArkUI'; 1718import { image } from '@kit.ImageKit'; 1719import { common2D, drawing } from '@kit.ArkGraphics2D'; 1720class DrawingRenderNode extends RenderNode { 1721pixelMap: image.PixelMap | null = null; 1722 draw(context : DrawContext) { 1723 const canvas = context.canvas; 1724 let pen = new drawing.Pen(); 1725 canvas.attachPen(pen); 1726 let rect: common2D.Rect = { left: 0, top: 0, right: 200, bottom: 200 }; 1727 canvas.drawImageRect(this.pixelMap, rect); 1728 canvas.detachPen(); 1729 } 1730} 1731``` 1732 1733### drawImageRectWithSrc<sup>12+</sup> 1734 1735drawImageRectWithSrc(pixelmap: image.PixelMap, srcRect: common2D.Rect, dstRect: common2D.Rect, samplingOptions?: SamplingOptions, constraint?: SrcRectConstraint): void 1736 1737Draws a portion of an image onto a specified area of the canvas. 1738 1739**System capability**: SystemCapability.Graphics.Drawing 1740 1741**Parameters** 1742 1743| Name | Type | Mandatory| Description | 1744| -------- | -------------------------------------------- | ---- | ------------------------------- | 1745| pixelmap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map of the image. | 1746| srcRect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | **Rectangle** object, which specifies the portion of the image to draw.| 1747| dstRect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | **Rectangle** object, which specifies the area of the canvas onto which the image will be drawn.| 1748| samplingOptions | [SamplingOptions](#samplingoptions12) | No | Sampling options. By default, the **SamplingOptions** object created using the no-argument constructor is used.| 1749| constraint | [SrcRectConstraint](#srcrectconstraint12) | No | Constraint type of the source rectangle. The default value is **STRICT**.| 1750 1751**Error codes** 1752 1753For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1754 1755| ID| Error Message| 1756| ------- | --------------------------------------------| 1757| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1758 1759**Example** 1760 1761```ts 1762import { RenderNode } from '@kit.ArkUI'; 1763import { image } from '@kit.ImageKit'; 1764import { common2D, drawing } from '@kit.ArkGraphics2D'; 1765class DrawingRenderNode extends RenderNode { 1766pixelMap: image.PixelMap | null = null; 1767 draw(context : DrawContext) { 1768 const canvas = context.canvas; 1769 let pen = new drawing.Pen(); 1770 canvas.attachPen(pen); 1771 let srcRect: common2D.Rect = { left: 0, top: 0, right: 100, bottom: 100 }; 1772 let dstRect: common2D.Rect = { left: 100, top: 100, right: 200, bottom: 200 }; 1773 canvas.drawImageRectWithSrc(this.pixelMap, srcRect, dstRect); 1774 canvas.detachPen(); 1775 } 1776} 1777``` 1778 1779### drawColor 1780 1781drawColor(color: common2D.Color, blendMode?: BlendMode): void 1782 1783Draws the background color. 1784 1785**System capability**: SystemCapability.Graphics.Drawing 1786 1787**Parameters** 1788 1789| Name | Type | Mandatory| Description | 1790| --------- | ---------------------------------------------------- | ---- | -------------------------------- | 1791| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255. | 1792| blendMode | [BlendMode](#blendmode) | No | Blend mode. The default mode is **SRC_OVER**.| 1793 1794**Error codes** 1795 1796For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1797 1798| ID| Error Message| 1799| ------- | --------------------------------------------| 1800| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 1801 1802**Example** 1803 1804```ts 1805import { RenderNode } from '@kit.ArkUI'; 1806import { common2D, drawing } from '@kit.ArkGraphics2D'; 1807class DrawingRenderNode extends RenderNode { 1808 draw(context : DrawContext) { 1809 const canvas = context.canvas; 1810 let color: common2D.Color = { 1811 alpha : 255, 1812 red: 0, 1813 green: 10, 1814 blue: 10 1815 } 1816 canvas.drawColor(color, drawing.BlendMode.CLEAR); 1817 } 1818} 1819``` 1820 1821### drawColor<sup>12+</sup> 1822 1823drawColor(alpha: number, red: number, green: number, blue: number, blendMode?: BlendMode): void 1824 1825Draws the background color. This API provides better performance than [drawColor](#drawcolor) and is recommended. 1826 1827**System capability**: SystemCapability.Graphics.Drawing 1828 1829**Parameters** 1830 1831| Name | Type | Mandatory| Description | 1832| --------- | ----------------------- | ---- | ------------------------------------------------- | 1833| alpha | number | Yes | Alpha channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.| 1834| red | number | Yes | Red channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 1835| green | number | Yes | Green channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 1836| blue | number | Yes | Blue channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 1837| blendMode | [BlendMode](#blendmode) | No | Blend mode. The default mode is **SRC_OVER**. | 1838 1839**Error codes** 1840 1841For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1842 1843| ID| Error Message| 1844| ------- | --------------------------------------------| 1845| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 1846 1847**Example** 1848 1849```ts 1850import { RenderNode } from '@kit.ArkUI'; 1851import { drawing } from '@kit.ArkGraphics2D'; 1852class DrawingRenderNode extends RenderNode { 1853 draw(context : DrawContext) { 1854 const canvas = context.canvas; 1855 canvas.drawColor(255, 0, 10, 10, drawing.BlendMode.CLEAR); 1856 } 1857} 1858``` 1859 1860### drawPixelMapMesh<sup>12+</sup> 1861 1862drawPixelMapMesh(pixelmap: image.PixelMap, meshWidth: number, meshHeight: number, vertices: Array\<number>, vertOffset: number, colors: Array\<number>, colorOffset: number): void 1863 1864Draws a pixel map based on a mesh, where mesh vertices are evenly distributed across the pixel map. 1865 1866**System capability**: SystemCapability.Graphics.Drawing 1867 1868**Parameters** 1869 1870| Name | Type | Mandatory| Description | 1871| ----------- | ------------- | ---- | ------------------------------- | 1872| pixelmap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map to draw.| 1873| meshWidth | number | Yes | Number of columns in the mesh. The value is an integer greater than 0.| 1874| meshHeight | number | Yes | Number of rows in the mesh. The value is an integer greater than 0.| 1875| vertices | Array\<number> | Yes | Array of vertices, which specify the position to draw. The value is a floating-point array and the size must be ((meshWidth+1) * (meshHeight+1) + vertOffset) * 2.| 1876| vertOffset | number | Yes | Number of vert elements to skip before drawing. The value is an integer greater than or equal to 0.| 1877| colors | Array\<number> | Yes | Array of colors, which specify the color at each vertex. The value is an integer array and can be null. The size must be (meshWidth+1) * (meshHeight+1) + colorOffset.| 1878| colorOffset | number | Yes | Number of color elements to skip before drawing. The value is an integer greater than or equal to 0.| 1879 1880**Error codes** 1881 1882For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1883 1884| ID| Error Message| 1885| ------- | --------------------------------------------| 1886| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1887 1888**Example** 1889 1890```ts 1891import { RenderNode } from '@kit.ArkUI'; 1892import { image } from '@kit.ImageKit'; 1893import { drawing } from '@kit.ArkGraphics2D'; 1894class DrawingRenderNode extends RenderNode { 1895 pixelMap: image.PixelMap | null = null; 1896 1897 async draw(context : DrawContext) { 1898 const canvas = context.canvas; 1899 if (this.pixelMap != null) { 1900 const brush = new drawing.Brush(); // Only brush is supported. There is no drawing effect when pen is used. 1901 canvas.attachBrush(brush); 1902 let verts : Array<number> = [0, 0, 50, 0, 410, 0, 0, 180, 50, 180, 410, 180, 0, 360, 50, 360, 410, 360]; // 18 1903 canvas.drawPixelMapMesh(this.pixelMap, 2, 2, verts, 0, null, 0); 1904 canvas.detachBrush(); 1905 } 1906 } 1907} 1908``` 1909 1910### clear<sup>12+</sup> 1911 1912clear(color: common2D.Color): void 1913 1914Clears the canvas with a given color. 1915 1916**System capability**: SystemCapability.Graphics.Drawing 1917 1918**Parameters** 1919 1920| Name | Type | Mandatory| Description | 1921| --------- | ---------------------------------------------------- | ---- | -------------------------------- | 1922| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255. | 1923 1924**Error codes** 1925 1926For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1927 1928| ID| Error Message| 1929| ------- | --------------------------------------------| 1930| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1931 1932**Example** 1933 1934```ts 1935import { RenderNode } from '@kit.ArkUI'; 1936import { common2D, drawing } from '@kit.ArkGraphics2D'; 1937class DrawingRenderNode extends RenderNode { 1938 draw(context : DrawContext) { 1939 const canvas = context.canvas; 1940 let color: common2D.Color = {alpha: 255, red: 255, green: 0, blue: 0}; 1941 canvas.clear(color); 1942 } 1943} 1944``` 1945 1946### getWidth<sup>12+</sup> 1947 1948getWidth(): number 1949 1950Obtains the canvas width. 1951 1952**System capability**: SystemCapability.Graphics.Drawing 1953 1954**Return value** 1955 1956| Type | Mandatory| Description | 1957| ------ | ---- | -------------- | 1958| number | Yes | Canvas width. The value is a floating point number.| 1959 1960**Example** 1961 1962```ts 1963import { RenderNode } from '@kit.ArkUI'; 1964import { drawing } from '@kit.ArkGraphics2D'; 1965class DrawingRenderNode extends RenderNode { 1966 draw(context : DrawContext) { 1967 const canvas = context.canvas; 1968 let width = canvas.getWidth(); 1969 console.info('get canvas width:' + width); 1970 } 1971} 1972``` 1973 1974### getHeight<sup>12+</sup> 1975 1976getHeight(): number 1977 1978Obtains the canvas height. 1979 1980**System capability**: SystemCapability.Graphics.Drawing 1981 1982**Return value** 1983 1984| Type | Mandatory| Description | 1985| ------ | ---- | -------------- | 1986| number | Yes | Canvas height. The value is a floating point number.| 1987 1988**Example** 1989 1990```ts 1991import { RenderNode } from '@kit.ArkUI'; 1992import { drawing } from '@kit.ArkGraphics2D'; 1993class DrawingRenderNode extends RenderNode { 1994 draw(context : DrawContext) { 1995 const canvas = context.canvas; 1996 let height = canvas.getHeight(); 1997 console.log('get canvas height:' + height); 1998 } 1999} 2000``` 2001 2002### drawOval<sup>12+</sup> 2003 2004drawOval(oval: common2D.Rect): void 2005 2006Draws an oval on the canvas. The shape and position of the oval are defined by the rectangle parameters that specify the oval boundary. 2007 2008**System capability**: SystemCapability.Graphics.Drawing 2009 2010**Parameters** 2011 2012| Name| Type | Mandatory| Description | 2013| ------ | -------------------------------------------------- | ---- | -------------- | 2014| oval | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangle. The oval inscribed within the rectangle is the oval to draw.| 2015 2016**Error codes** 2017 2018For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2019 2020| ID| Error Message| 2021| ------- | --------------------------------------------| 2022| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2023 2024**Example** 2025 2026```ts 2027import { RenderNode } from '@kit.ArkUI'; 2028import { common2D, drawing } from '@kit.ArkGraphics2D'; 2029class DrawingRenderNode extends RenderNode { 2030 draw(context : DrawContext) { 2031 const canvas = context.canvas; 2032 const pen = new drawing.Pen(); 2033 pen.setStrokeWidth(5); 2034 const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 2035 pen.setColor(color); 2036 canvas.attachPen(pen); 2037 const rect: common2D.Rect = {left:100, top:50, right:400, bottom:500}; 2038 canvas.drawOval(rect); 2039 canvas.detachPen(); 2040 } 2041} 2042``` 2043 2044### drawArc<sup>12+</sup> 2045 2046drawArc(arc: common2D.Rect, startAngle: number, sweepAngle: number): void 2047 2048Draws an arc on the canvas, with the start angle and sweep angle specified. 2049 2050**System capability**: SystemCapability.Graphics.Drawing 2051 2052**Parameters** 2053 2054| Name| Type | Mandatory| Description | 2055| ------ | -------------------------------------------------- | ---- | -------------- | 2056| arc | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangular boundary that encapsulates the oval including the arc.| 2057| startAngle | number | Yes | Start angle, in degrees. The value is a floating point number. When the degree is 0, the start point is located at the right end of the oval. A positive number indicates that the start point is placed clockwise, and a negative number indicates that the start point is placed counterclockwise.| 2058| sweepAngle | number | Yes | Angle to sweep, in degrees. The value is a floating point number. A positive number indicates a clockwise sweep, and a negative value indicates a counterclockwise swipe.| 2059 2060**Error codes** 2061 2062For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2063 2064| ID| Error Message| 2065| ------- | --------------------------------------------| 2066| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2067 2068**Example** 2069 2070```ts 2071import { RenderNode } from '@kit.ArkUI'; 2072import { common2D, drawing } from '@kit.ArkGraphics2D'; 2073class DrawingRenderNode extends RenderNode { 2074 draw(context : DrawContext) { 2075 const canvas = context.canvas; 2076 const pen = new drawing.Pen(); 2077 pen.setStrokeWidth(5); 2078 const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 2079 pen.setColor(color); 2080 canvas.attachPen(pen); 2081 const rect: common2D.Rect = {left:100, top:50, right:400, bottom:200}; 2082 canvas.drawArc(rect, 90, 180); 2083 canvas.detachPen(); 2084 } 2085} 2086``` 2087 2088### drawPoint 2089 2090drawPoint(x: number, y: number): void 2091 2092Draws a point. 2093 2094**System capability**: SystemCapability.Graphics.Drawing 2095 2096**Parameters** 2097 2098| Name| Type | Mandatory| Description | 2099| ------ | ------ | ---- | ------------------- | 2100| x | number | Yes | X coordinate of the point. The value is a floating point number.| 2101| y | number | Yes | Y coordinate of the point. The value is a floating point number.| 2102 2103**Error codes** 2104 2105For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2106 2107| ID| Error Message| 2108| ------- | --------------------------------------------| 2109| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2110 2111**Example** 2112 2113```ts 2114import { RenderNode } from '@kit.ArkUI'; 2115import { drawing } from '@kit.ArkGraphics2D'; 2116class DrawingRenderNode extends RenderNode { 2117 draw(context : DrawContext) { 2118 const canvas = context.canvas; 2119 const pen = new drawing.Pen(); 2120 pen.setStrokeWidth(5); 2121 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2122 canvas.attachPen(pen); 2123 canvas.drawPoint(10, 10); 2124 canvas.detachPen(); 2125 } 2126} 2127``` 2128 2129### drawPoints<sup>12+</sup> 2130 2131drawPoints(points: Array\<common2D.Point>, mode?: PointMode): void 2132 2133Draws a group of points, line segments, or polygons on the canvas, with the specified drawing mode. An array is used to hold these points. 2134 2135**System capability**: SystemCapability.Graphics.Drawing 2136 2137**Parameters** 2138 2139| Name | Type | Mandatory | Description | 2140| ---- | ---------------------------------------- | ---- | --------- | 2141| points | Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Yes | Array that holds the points to draw. The length cannot be 0. | 2142| mode | [PointMode](#pointmode12) | No | Mode in which the points are drawn. The default value is **drawing.PointMode.POINTS**.| 2143 2144**Error codes** 2145 2146For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2147 2148| ID| Error Message| 2149| ------- | --------------------------------------------| 2150| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 2151 2152**Example** 2153 2154```ts 2155import { RenderNode } from '@kit.ArkUI'; 2156import { common2D, drawing } from '@kit.ArkGraphics2D'; 2157class DrawingRenderNode extends RenderNode { 2158 draw(context : DrawContext) { 2159 const canvas = context.canvas; 2160 const pen = new drawing.Pen(); 2161 pen.setStrokeWidth(30); 2162 const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 2163 pen.setColor(color); 2164 canvas.attachPen(pen); 2165 canvas.drawPoints([{x: 100, y: 200}, {x: 150, y: 230}, {x: 200, y: 300}], drawing.PointMode.POINTS); 2166 canvas.detachPen(); 2167 } 2168} 2169``` 2170 2171### drawPath 2172 2173drawPath(path: Path): void 2174 2175Draws a custom path, which contains a set of path outlines. Each path outline can be open or closed. 2176 2177**System capability**: SystemCapability.Graphics.Drawing 2178 2179**Parameters** 2180 2181| Name| Type | Mandatory| Description | 2182| ------ | ------------- | ---- | ------------------ | 2183| path | [Path](#path) | Yes | **Path** object to draw.| 2184 2185**Error codes** 2186 2187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2188 2189| ID| Error Message| 2190| ------- | --------------------------------------------| 2191| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2192 2193**Example** 2194 2195```ts 2196import { RenderNode } from '@kit.ArkUI'; 2197import { drawing } from '@kit.ArkGraphics2D'; 2198class DrawingRenderNode extends RenderNode { 2199 draw(context : DrawContext) { 2200 const canvas = context.canvas; 2201 const pen = new drawing.Pen(); 2202 pen.setStrokeWidth(5); 2203 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2204 let path = new drawing.Path(); 2205 path.moveTo(10,10); 2206 path.cubicTo(10, 10, 10, 10, 15, 15); 2207 path.close(); 2208 canvas.attachPen(pen); 2209 canvas.drawPath(path); 2210 canvas.detachPen(); 2211 } 2212} 2213``` 2214 2215### drawLine 2216 2217drawLine(x0: number, y0: number, x1: number, y1: number): void 2218 2219Draws a line segment from the start point to the end point. If the coordinates of the start point are the same as those of the end point, nothing is drawn. 2220 2221**System capability**: SystemCapability.Graphics.Drawing 2222 2223**Parameters** 2224 2225| Name| Type | Mandatory| Description | 2226| ------ | ------ | ---- | ----------------------- | 2227| x0 | number | Yes | X coordinate of the start point of the line segment. The value is a floating point number.| 2228| y0 | number | Yes | Y coordinate of the start point of the line segment. The value is a floating point number.| 2229| x1 | number | Yes | X coordinate of the end point of the line segment. The value is a floating point number.| 2230| y1 | number | Yes | Y coordinate of the end point of the line segment. The value is a floating point number.| 2231 2232**Error codes** 2233 2234For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2235 2236| ID| Error Message| 2237| ------- | --------------------------------------------| 2238| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2239 2240**Example** 2241 2242```ts 2243import { RenderNode } from '@kit.ArkUI'; 2244import { drawing } from '@kit.ArkGraphics2D'; 2245class DrawingRenderNode extends RenderNode { 2246 draw(context : DrawContext) { 2247 const canvas = context.canvas; 2248 const pen = new drawing.Pen(); 2249 pen.setStrokeWidth(5); 2250 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2251 canvas.attachPen(pen); 2252 canvas.drawLine(0, 0, 20, 20); 2253 canvas.detachPen(); 2254 } 2255} 2256``` 2257 2258### drawTextBlob 2259 2260drawTextBlob(blob: TextBlob, x: number, y: number): void 2261 2262Draws a text blob. If the typeface used to construct **blob** does not support a character, that character will not be drawn. 2263 2264**System capability**: SystemCapability.Graphics.Drawing 2265 2266**Parameters** 2267 2268| Name| Type | Mandatory| Description | 2269| ------ | --------------------- | ---- | ------------------------------------------ | 2270| blob | [TextBlob](#textblob) | Yes | **TextBlob** object. | 2271| x | number | Yes | X coordinate of the left point (red point in the figure below) of the text baseline (blue line in the figure below). The value is a floating point number.| 2272| y | number | Yes | Y coordinate of the left point (red point in the figure below) of the text baseline (blue line in the figure below). The value is a floating point number.| 2273 2274 2275 2276**Error codes** 2277 2278For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2279 2280| ID| Error Message| 2281| ------- | --------------------------------------------| 2282| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2283 2284**Example** 2285 2286```ts 2287import { RenderNode } from '@kit.ArkUI'; 2288import { drawing } from '@kit.ArkGraphics2D'; 2289class DrawingRenderNode extends RenderNode { 2290 draw(context : DrawContext) { 2291 const canvas = context.canvas; 2292 const brush = new drawing.Brush(); 2293 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2294 const font = new drawing.Font(); 2295 font.setSize(20); 2296 const textBlob = drawing.TextBlob.makeFromString("Hello, drawing", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 2297 canvas.attachBrush(brush); 2298 canvas.drawTextBlob(textBlob, 20, 20); 2299 canvas.detachBrush(); 2300 } 2301} 2302``` 2303 2304### drawSingleCharacter<sup>12+</sup> 2305 2306drawSingleCharacter(text: string, font: Font, x: number, y: number): void 2307 2308Draws a single character. If the typeface of the current font does not support the character to draw, the system typeface is used to draw the character. 2309 2310**System capability**: SystemCapability.Graphics.Drawing 2311 2312**Parameters** 2313 2314| Name| Type | Mandatory| Description | 2315| ------ | ------------------- | ---- | ----------- | 2316| text | string | Yes | Single character to draw. The length of the string must be 1. | 2317| font | [Font](#font) | Yes | **Font** object. | 2318| x | number | Yes | X coordinate of the left point (red point in the figure below) of the character baseline (blue line in the figure below). The value is a floating point number.| 2319| y | number | Yes | Y coordinate of the left point (red point in the figure below) of the character baseline (blue line in the figure below). The value is a floating point number.| 2320 2321 2322 2323**Error codes** 2324 2325For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2326 2327| ID| Error Message| 2328| ------- | --------------------------------------------| 2329| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 2330 2331**Example** 2332 2333```ts 2334import { RenderNode } from '@kit.ArkUI'; 2335import { drawing } from '@kit.ArkGraphics2D'; 2336 2337class DrawingRenderNode extends RenderNode { 2338 draw(context : DrawContext) { 2339 const canvas = context.canvas; 2340 const brush = new drawing.Brush(); 2341 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2342 const font = new drawing.Font(); 2343 font.setSize(20); 2344 canvas.attachBrush(brush); 2345 canvas.drawSingleCharacter ("Hello", font, 100, 100); 2346 canvas.drawSingleCharacter ("drawing", font, 120, 100); 2347 canvas.detachBrush(); 2348 } 2349} 2350``` 2351 2352### drawRegion<sup>12+</sup> 2353 2354drawRegion(region: Region): void 2355 2356Draws a region. 2357 2358**System capability**: SystemCapability.Graphics.Drawing 2359 2360**Parameters** 2361 2362| Name| Type | Mandatory| Description | 2363| ------ | ------------------- | ---- | ----------- | 2364| region | [Region](#region12) | Yes | Region to draw. | 2365 2366**Error codes** 2367 2368For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2369 2370| ID| Error Message| 2371| ------- | --------------------------------------------| 2372| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2373 2374**Example** 2375 2376```ts 2377import { RenderNode } from '@kit.ArkUI'; 2378class DrawingRenderNode extends RenderNode { 2379 draw(context : DrawContext) { 2380 const canvas = context.canvas; 2381 const pen = new drawing.Pen(); 2382 let region = new drawing.Region(); 2383 pen.setStrokeWidth(10); 2384 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 2385 canvas.attachPen(pen); 2386 region.setRect(100, 100, 400, 400); 2387 canvas.drawRegion(region); 2388 canvas.detachPen(); 2389 } 2390} 2391``` 2392 2393### attachPen 2394 2395attachPen(pen: Pen): void 2396 2397Attaches a pen to a canvas so that the canvas can use the style and color of the pen to outline a shape. 2398 2399> **NOTE** 2400> 2401> If the pen effect changes after this API is called, you must call the API again if you want to use the new effect in the subsequent drawing. 2402 2403**System capability**: SystemCapability.Graphics.Drawing 2404 2405**Parameters** 2406 2407| Name| Type | Mandatory| Description | 2408| ------ | ----------- | ---- | ---------- | 2409| pen | [Pen](#pen) | Yes | **Pen** object.| 2410 2411**Error codes** 2412 2413For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2414 2415| ID| Error Message| 2416| ------- | --------------------------------------------| 2417| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2418 2419**Example** 2420 2421```ts 2422import { RenderNode } from '@kit.ArkUI'; 2423import { drawing } from '@kit.ArkGraphics2D'; 2424class DrawingRenderNode extends RenderNode { 2425 draw(context : DrawContext) { 2426 const canvas = context.canvas; 2427 const pen = new drawing.Pen(); 2428 pen.setStrokeWidth(5); 2429 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2430 canvas.attachPen(pen); 2431 canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 }); 2432 canvas.detachPen(); 2433 } 2434} 2435``` 2436 2437### attachBrush 2438 2439attachBrush(brush: Brush): void 2440 2441Attaches a brush to a canvas so that the canvas can use the style and color of the brush to fill in a shape. 2442 2443> **NOTE** 2444> 2445> If the brush effect changes after this API is called, you must call the API again if you want to use the new effect in the subsequent drawing. 2446 2447**System capability**: SystemCapability.Graphics.Drawing 2448 2449**Parameters** 2450 2451| Name| Type | Mandatory| Description | 2452| ------ | --------------- | ---- | ---------- | 2453| brush | [Brush](#brush) | Yes | **Brush** object.| 2454 2455**Error codes** 2456 2457For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2458 2459| ID| Error Message| 2460| ------- | --------------------------------------------| 2461| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2462 2463**Example** 2464 2465```ts 2466import { RenderNode } from '@kit.ArkUI'; 2467import { drawing } from '@kit.ArkGraphics2D'; 2468class DrawingRenderNode extends RenderNode { 2469 draw(context : DrawContext) { 2470 const canvas = context.canvas; 2471 const brush = new drawing.Brush(); 2472 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2473 canvas.attachBrush(brush); 2474 canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 }); 2475 canvas.detachBrush(); 2476 } 2477} 2478``` 2479 2480### detachPen 2481 2482detachPen(): void 2483 2484Detaches the pen from a canvas so that the canvas can no longer use the style and color of the pen to outline a shape. 2485 2486**System capability**: SystemCapability.Graphics.Drawing 2487 2488**Example** 2489 2490```ts 2491import { RenderNode } from '@kit.ArkUI'; 2492import { drawing } from '@kit.ArkGraphics2D'; 2493class DrawingRenderNode extends RenderNode { 2494 draw(context : DrawContext) { 2495 const canvas = context.canvas; 2496 const pen = new drawing.Pen(); 2497 pen.setStrokeWidth(5); 2498 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2499 canvas.attachPen(pen); 2500 canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 }); 2501 canvas.detachPen(); 2502 } 2503} 2504``` 2505 2506### detachBrush 2507 2508detachBrush(): void 2509 2510Detaches the brush from a canvas so that the canvas can no longer use the style and color of the brush to fill in a shape. 2511 2512**System capability**: SystemCapability.Graphics.Drawing 2513 2514**Example** 2515 2516```ts 2517import { RenderNode } from '@kit.ArkUI'; 2518import { drawing } from '@kit.ArkGraphics2D'; 2519class DrawingRenderNode extends RenderNode { 2520 draw(context : DrawContext) { 2521 const canvas = context.canvas; 2522 const brush = new drawing.Brush(); 2523 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2524 canvas.attachBrush(brush); 2525 canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 }); 2526 canvas.detachBrush(); 2527 } 2528} 2529``` 2530 2531### clipPath<sup>12+</sup> 2532 2533clipPath(path: Path, clipOp?: ClipOp, doAntiAlias?: boolean): void 2534 2535Clips a path. 2536 2537**System capability**: SystemCapability.Graphics.Drawing 2538 2539**Parameters** 2540 2541| Name | Type | Mandatory| Description | 2542| ------------ | ----------------- | ---- | ------------------------------------| 2543| path | [Path](#path) | Yes | **Path** object. | 2544| clipOp | [ClipOp](#clipop12) | No | Clip mode. The default value is **INTERSECT**. | 2545| doAntiAlias | boolean | No | Whether to enable anti-aliasing. The value **true** means to enable anti-aliasing, and **false** means the opposite. The default value is **false**.| 2546 2547**Error codes** 2548 2549For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2550 2551| ID| Error Message| 2552| ------- | --------------------------------------------| 2553| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2554 2555**Example** 2556 2557```ts 2558import { RenderNode } from '@kit.ArkUI'; 2559import { common2D, drawing } from '@kit.ArkGraphics2D'; 2560class DrawingRenderNode extends RenderNode { 2561 draw(context : DrawContext) { 2562 const canvas = context.canvas; 2563 const pen = new drawing.Pen(); 2564 pen.setStrokeWidth(5); 2565 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2566 let path = new drawing.Path(); 2567 path.moveTo(10, 10); 2568 path.cubicTo(10, 10, 10, 10, 15, 15); 2569 path.close(); 2570 canvas.attachPen(pen); 2571 canvas.clipPath(path, drawing.ClipOp.DIFFERENCE, true); 2572 canvas.detachPen(); 2573 } 2574} 2575``` 2576 2577### clipRect<sup>12+</sup> 2578 2579clipRect(rect: common2D.Rect, clipOp?: ClipOp, doAntiAlias?: boolean): void 2580 2581Clips a rectangle. 2582 2583**System capability**: SystemCapability.Graphics.Drawing 2584 2585**Parameters** 2586 2587| Name | Type | Mandatory | Description | 2588| ----------- | ---------------------------------------- | ---- | ------------------- | 2589| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangle. | 2590| clipOp | [ClipOp](#clipop12) | No | Clip mode. The default value is **INTERSECT**. | 2591| doAntiAlias | boolean | No | Whether to enable anti-aliasing. The value **true** means to enable anti-aliasing, and **false** means the opposite. The default value is **false**.| 2592 2593**Error codes** 2594 2595For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2596 2597| ID| Error Message| 2598| ------- | --------------------------------------------| 2599| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2600 2601**Example** 2602 2603```ts 2604import { RenderNode } from '@kit.ArkUI'; 2605import { common2D, drawing } from '@kit.ArkGraphics2D'; 2606class DrawingRenderNode extends RenderNode { 2607 draw(context : DrawContext) { 2608 const canvas = context.canvas; 2609 const pen = new drawing.Pen(); 2610 pen.setStrokeWidth(5); 2611 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2612 canvas.attachPen(pen); 2613 canvas.clipRect({left : 10, right : 500, top : 300, bottom : 900}, drawing.ClipOp.DIFFERENCE, true); 2614 canvas.detachPen(); 2615 } 2616} 2617``` 2618 2619### save<sup>12+</sup> 2620 2621save(): number 2622 2623Saves the current canvas status (canvas matrix) to the top of the stack. 2624 2625**System capability**: SystemCapability.Graphics.Drawing 2626 2627**Return value** 2628 2629| Type | Description | 2630| ------ | ------------------ | 2631| number | Number of canvas statuses. The value is a positive integer.| 2632 2633**Example** 2634 2635```ts 2636import { RenderNode } from '@kit.ArkUI'; 2637import { common2D, drawing } from '@kit.ArkGraphics2D'; 2638class DrawingRenderNode extends RenderNode { 2639 draw(context : DrawContext) { 2640 const canvas = context.canvas; 2641 let rect: common2D.Rect = {left: 10, right: 200, top: 100, bottom: 300}; 2642 canvas.drawRect(rect); 2643 let saveCount = canvas.save(); 2644 } 2645} 2646``` 2647 2648### saveLayer<sup>12+</sup> 2649 2650saveLayer(rect?: common2D.Rect | null, brush?: Brush | null): number 2651 2652Saves the matrix and cropping region of the canvas, and allocates a bitmap for subsequent drawing. If you call [restore](#restore12), the changes made to the matrix and clipping region are discarded, and the bitmap is drawn. 2653 2654**System capability**: SystemCapability.Graphics.Drawing 2655 2656**Parameters** 2657 2658| Name | Type | Mandatory | Description | 2659| ---- | ------ | ---- | ----------------- | 2660| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect)\|null | No | **Rect** object, which is used to limit the size of the graphics layer. The default value is the current canvas size.| 2661| brush | [Brush](#brush)\|null | No | **Brush** object. The alpha value, filter effect, and blend mode of the brush are applied when the bitmap is drawn. If null is passed in, no effect is applied.| 2662 2663**Return value** 2664 2665| Type | Description | 2666| ------ | ------------------ | 2667| number | Number of canvas statuses that have been saved. The value is a positive integer.| 2668 2669**Error codes** 2670 2671For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2672 2673| ID| Error Message| 2674| ------- | --------------------------------------------| 2675| 401 | Parameter error. Possible causes: Mandatory parameters are left unspecified. | 2676 2677**Example** 2678 2679```ts 2680import { RenderNode } from '@kit.ArkUI'; 2681import { common2D, drawing } from '@kit.ArkGraphics2D'; 2682class DrawingRenderNode extends RenderNode { 2683 draw(context : DrawContext) { 2684 const canvas = context.canvas; 2685 canvas.saveLayer(null, null); 2686 const brushRect = new drawing.Brush(); 2687 const colorRect: common2D.Color = {alpha: 255, red: 255, green: 255, blue: 0}; 2688 brushRect.setColor(colorRect); 2689 canvas.attachBrush(brushRect); 2690 const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500}; 2691 canvas.drawRect(rect); 2692 2693 const brush = new drawing.Brush(); 2694 brush.setBlendMode(drawing.BlendMode.DST_OUT); 2695 canvas.saveLayer(rect, brush); 2696 2697 const brushCircle = new drawing.Brush(); 2698 const colorCircle: common2D.Color = {alpha: 255, red: 0, green: 0, blue: 255}; 2699 brushCircle.setColor(colorCircle); 2700 canvas.attachBrush(brushCircle); 2701 canvas.drawCircle(500, 500, 200); 2702 canvas.restore(); 2703 canvas.restore(); 2704 canvas.detachBrush(); 2705 } 2706} 2707``` 2708 2709### scale<sup>12+</sup> 2710 2711scale(sx: number, sy: number): void 2712 2713Scales the canvas. 2714 2715**System capability**: SystemCapability.Graphics.Drawing 2716 2717**Parameters** 2718 2719| Name | Type | Mandatory | Description | 2720| ---- | ------ | ---- | ----------------- | 2721| sx | number | Yes | Scale ratio on the X axis. The value is a floating point number.| 2722| sy | number | Yes | Scale ratio on the Y axis. The value is a floating point number.| 2723 2724**Error codes** 2725 2726For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2727 2728| ID| Error Message| 2729| ------- | --------------------------------------------| 2730| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2731 2732**Example** 2733 2734```ts 2735import { RenderNode } from '@kit.ArkUI'; 2736import { common2D, drawing } from '@kit.ArkGraphics2D'; 2737class DrawingRenderNode extends RenderNode { 2738 draw(context : DrawContext) { 2739 const canvas = context.canvas; 2740 const pen = new drawing.Pen(); 2741 pen.setStrokeWidth(5); 2742 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2743 canvas.attachPen(pen); 2744 canvas.scale(2, 0.5); 2745 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2746 canvas.detachPen(); 2747 } 2748} 2749``` 2750 2751### skew<sup>12+</sup> 2752 2753skew(sx: number, sy: number) : void 2754 2755Skews the canvas in both the horizontal and vertical directions. 2756 2757**System capability**: SystemCapability.Graphics.Drawing 2758 2759**Parameters** 2760 2761| Name | Type | Mandatory | Description | 2762| ---- | ------ | ---- | ----------------- | 2763| sx | number | Yes | Amount of tilt on the X axis. The value is a floating point number. | 2764| sy | number | Yes | Amount of tilt on the Y axis. The value is a floating point number. | 2765 2766**Error codes** 2767 2768For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2769 2770| ID| Error Message| 2771| ------- | --------------------------------------------| 2772| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2773 2774**Example** 2775 2776```ts 2777import { RenderNode } from '@kit.ArkUI'; 2778import { common2D, drawing } from '@kit.ArkGraphics2D'; 2779class DrawingRenderNode extends RenderNode { 2780 draw(context : DrawContext) { 2781 const canvas = context.canvas; 2782 const pen = new drawing.Pen(); 2783 pen.setStrokeWidth(5); 2784 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2785 canvas.attachPen(pen); 2786 canvas.skew(0.1, 0.1); 2787 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2788 canvas.detachPen(); 2789 } 2790} 2791``` 2792 2793### rotate<sup>12+</sup> 2794 2795rotate(degrees: number, sx: number, sy: number) : void 2796 2797Rotates the canvas by a certain angle. 2798 2799**System capability**: SystemCapability.Graphics.Drawing 2800 2801**Parameters** 2802 2803| Name | Type | Mandatory | Description | 2804| ---- | ------ | ------ | ------------------------ | 2805| degrees | number | Yes | Angle to rotate, in degrees. The value is a floating point number. A positive value indicates a clockwise rotation, and a negative value indicates a counterclockwise rotation. | 2806| sx | number | Yes | X coordinate of the rotation center. The value is a floating point number.| 2807| sy | number | Yes | Y coordinate of the rotation center. The value is a floating point number.| 2808 2809**Error codes** 2810 2811For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2812 2813| ID| Error Message| 2814| ------- | --------------------------------------------| 2815| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2816 2817**Example** 2818 2819```ts 2820import { RenderNode } from '@kit.ArkUI'; 2821import { common2D, drawing } from '@kit.ArkGraphics2D'; 2822class DrawingRenderNode extends RenderNode { 2823 draw(context : DrawContext) { 2824 const canvas = context.canvas; 2825 const pen = new drawing.Pen(); 2826 pen.setStrokeWidth(5); 2827 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2828 canvas.attachPen(pen); 2829 canvas.rotate(30, 100, 100); 2830 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2831 canvas.detachPen(); 2832 } 2833} 2834``` 2835 2836### translate<sup>12+</sup> 2837 2838translate(dx: number, dy: number): void 2839 2840Translates the canvas by a given distance. 2841 2842**System capability**: SystemCapability.Graphics.Drawing 2843 2844**Parameters** 2845 2846| Name| Type | Mandatory| Description | 2847| ----- | ------ | ---- | ------------------- | 2848| dx | number | Yes | Distance to translate on the X axis. The value is a floating point number. | 2849| dy | number | Yes | Distance to translate on the Y axis. The value is a floating point number. | 2850 2851**Error codes** 2852 2853For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2854 2855| ID| Error Message| 2856| ------- | --------------------------------------------| 2857| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2858 2859**Example** 2860 2861```ts 2862import { RenderNode } from '@kit.ArkUI'; 2863import { common2D, drawing } from '@kit.ArkGraphics2D'; 2864class DrawingRenderNode extends RenderNode { 2865 draw(context : DrawContext) { 2866 const canvas = context.canvas; 2867 const pen = new drawing.Pen(); 2868 pen.setStrokeWidth(5); 2869 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2870 canvas.attachPen(pen); 2871 canvas.translate(10, 10); 2872 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2873 canvas.detachPen(); 2874 } 2875} 2876``` 2877 2878### getSaveCount<sup>12+</sup> 2879 2880getSaveCount(): number 2881 2882Obtains the number of canvas statuses (canvas matrices) saved in the stack. 2883 2884**System capability**: SystemCapability.Graphics.Drawing 2885 2886**Return value** 2887 2888| Type | Description | 2889| ------ | ------------------------------------ | 2890| number | Number of canvas statuses that have been saved. The value is a positive integer.| 2891 2892**Example** 2893 2894```ts 2895import { RenderNode } from '@kit.ArkUI'; 2896import { common2D, drawing } from '@kit.ArkGraphics2D'; 2897class DrawingRenderNode extends RenderNode { 2898 draw(context : DrawContext) { 2899 const canvas = context.canvas; 2900 const pen = new drawing.Pen(); 2901 pen.setStrokeWidth(5); 2902 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2903 canvas.attachPen(pen); 2904 canvas.drawRect({left: 10, right: 200, top: 100, bottom: 300}); 2905 canvas.save(); 2906 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2907 canvas.getSaveCount(); 2908 canvas.detachPen(); 2909 } 2910} 2911``` 2912 2913### restoreToCount<sup>12+</sup> 2914 2915restoreToCount(count: number): void 2916 2917Restores to a given number of canvas statuses (canvas matrices). 2918 2919**System capability**: SystemCapability.Graphics.Drawing 2920 2921**Parameters** 2922 2923| Name | Type | Mandatory | Description | 2924| ----- | ------ | ---- | ----------------------------- | 2925| count | number | Yes | Depth of the canvas statuses to restore. The value is an integer. If the value is less than or equal to 1, the canvas is restored to the initial state. If the value is greater than the number of canvas statuses that have been saved, no operation is performed.| 2926 2927**Error codes** 2928 2929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2930 2931| ID| Error Message| 2932| ------- | --------------------------------------------| 2933| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 2934 2935**Example** 2936 2937```ts 2938import { RenderNode } from '@kit.ArkUI'; 2939import { common2D, drawing } from '@kit.ArkGraphics2D'; 2940class DrawingRenderNode extends RenderNode { 2941 draw(context : DrawContext) { 2942 const canvas = context.canvas; 2943 const pen = new drawing.Pen(); 2944 pen.setStrokeWidth(5); 2945 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2946 canvas.attachPen(pen); 2947 canvas.drawRect({left: 10, right: 200, top: 100, bottom: 300}); 2948 canvas.save(); 2949 canvas.drawRect({left: 10, right: 200, top: 100, bottom: 500}); 2950 canvas.save(); 2951 canvas.drawRect({left: 100, right: 300, top: 100, bottom: 500}); 2952 canvas.save(); 2953 canvas.restoreToCount(2); 2954 canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900}); 2955 canvas.detachPen(); 2956 } 2957} 2958``` 2959 2960### restore<sup>12+</sup> 2961 2962restore(): void 2963 2964Restores the canvas status (canvas matrix) saved on the top of the stack. 2965 2966**System capability**: SystemCapability.Graphics.Drawing 2967 2968**Example** 2969 2970```ts 2971import { RenderNode } from '@kit.ArkUI'; 2972import { common2D, drawing } from '@kit.ArkGraphics2D'; 2973class DrawingRenderNode extends RenderNode { 2974 draw(context : DrawContext) { 2975 const canvas = context.canvas; 2976 const pen = new drawing.Pen(); 2977 pen.setStrokeWidth(5); 2978 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 2979 canvas.attachPen(pen); 2980 canvas.restore(); 2981 canvas.detachPen(); 2982 } 2983} 2984``` 2985 2986### concatMatrix<sup>12+</sup> 2987 2988concatMatrix(matrix: Matrix): void 2989 2990Preconcats the existing matrix of the canvas with the passed-in matrix. The drawing operation triggered before this API is called is not affected. 2991 2992**System capability**: SystemCapability.Graphics.Drawing 2993 2994**Parameters** 2995 2996| Name | Type | Mandatory | Description | 2997| ------ | ----------------- | ---- | ----- | 2998| matrix | [Matrix](#matrix12) | Yes | **Matrix** object.| 2999 3000**Error codes** 3001 3002For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3003 3004| ID| Error Message| 3005| ------- | --------------------------------------------| 3006| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3007 3008**Example** 3009 3010```ts 3011import { RenderNode } from '@kit.ArkUI'; 3012import { drawing } from '@kit.ArkGraphics2D'; 3013class DrawingRenderNode extends RenderNode { 3014 draw(context : DrawContext) { 3015 const canvas = context.canvas; 3016 let matrix = new drawing.Matrix(); 3017 matrix.setMatrix([5, 0, 0, 0, 1, 2, 0, 0, 1]); 3018 canvas.concatMatrix(matrix); 3019 } 3020} 3021``` 3022 3023### setMatrix<sup>12+</sup> 3024 3025setMatrix(matrix: Matrix): void 3026 3027Sets a matrix for the canvas. 3028 3029**System capability**: SystemCapability.Graphics.Drawing 3030 3031**Parameters** 3032 3033| Name | Type | Mandatory | Description | 3034| ------ | ----------------- | ---- | ----- | 3035| matrix | [Matrix](#matrix12) | Yes | **Matrix** object.| 3036 3037**Error codes** 3038 3039For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3040 3041| ID| Error Message| 3042| ------- | --------------------------------------------| 3043| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3044 3045**Example** 3046 3047```ts 3048import { RenderNode } from '@kit.ArkUI'; 3049import { drawing } from '@kit.ArkGraphics2D'; 3050class DrawingRenderNode extends RenderNode { 3051 draw(context : DrawContext) { 3052 const canvas = context.canvas; 3053 let matrix = new drawing.Matrix() 3054 matrix.setMatrix([5, 0, 0, 0, 1, 1, 0, 0, 1]); 3055 canvas.setMatrix(matrix); 3056 } 3057} 3058``` 3059 3060### isClipEmpty<sup>12+</sup> 3061 3062isClipEmpty(): boolean 3063 3064Checks whether the region that can be drawn is empty after clipping. 3065 3066**System capability**: SystemCapability.Graphics.Drawing 3067 3068**Return value** 3069 3070| Type | Description | 3071| --------------------- | -------------- | 3072| boolean | Chek result. The value **true** means that the region is empty, and **false** means the opposite.| 3073 3074**Example** 3075 3076```ts 3077import { RenderNode } from '@kit.ArkUI'; 3078import { drawing } from '@kit.ArkGraphics2D'; 3079class DrawingRenderNode extends RenderNode { 3080 draw(context : DrawContext) { 3081 const canvas = context.canvas; 3082 if (canvas.isClipEmpty()) { 3083 console.info("canvas.isClipEmpty() returned true"); 3084 } else { 3085 console.info("canvas.isClipEmpty() returned false"); 3086 } 3087 } 3088} 3089``` 3090 3091### clipRegion<sup>12+</sup> 3092 3093clipRegion(region: Region, clipOp?: ClipOp): void 3094 3095Clips a region on the canvas. 3096 3097**System capability**: SystemCapability.Graphics.Drawing 3098 3099**Parameters** 3100 3101| Name | Type | Mandatory| Description | 3102| --------------- | ------- | ---- | ----------------------------------------------------------- | 3103| region | [Region](#region12) | Yes | **Region** object, which indicates the range to clip.| 3104| clipOp | [ClipOp](#clipop12) | No | Clipping mode. The default value is **INTERSECT**.| 3105 3106**Error codes** 3107 3108For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3109 3110| ID| Error Message| 3111| ------- | --------------------------------------------| 3112| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3113 3114**Example** 3115 3116```ts 3117import { RenderNode } from '@kit.ArkUI'; 3118import { drawing } from '@kit.ArkGraphics2D'; 3119class DrawingRenderNode extends RenderNode { 3120 draw(context : DrawContext) { 3121 const canvas = context.canvas; 3122 let region : drawing.Region = new drawing.Region(); 3123 region.setRect(0, 0, 500, 500); 3124 canvas.clipRegion(region); 3125 } 3126} 3127``` 3128 3129### clipRoundRect<sup>12+</sup> 3130 3131clipRoundRect(roundRect: RoundRect, clipOp?: ClipOp, doAntiAlias?: boolean): void 3132 3133Clips a rounded rectangle on the canvas. 3134 3135**System capability**: SystemCapability.Graphics.Drawing 3136 3137**Parameters** 3138 3139| Name | Type | Mandatory| Description | 3140| --------------- | ------- | ---- | ----------------------------------------------------------- | 3141| roundRect | [RoundRect](#roundrect12) | Yes | **RoundRect** object, which indicates the range to clip.| 3142| clipOp | [ClipOp](#clipop12) | No | Clipping mode. The default value is **INTERSECT**.| 3143| doAntiAlias | boolean | No | Whether to enable anti-aliasing. The value **true** means to enable anti-aliasing, and **false** means the opposite. The default value is **false**.| 3144 3145**Error codes** 3146 3147For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3148 3149| ID| Error Message| 3150| ------- | --------------------------------------------| 3151| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3152 3153**Example** 3154 3155```ts 3156import { RenderNode } from '@kit.ArkUI'; 3157import { common2D, drawing } from '@kit.ArkGraphics2D'; 3158class DrawingRenderNode extends RenderNode { 3159 draw(context : DrawContext) { 3160 const canvas = context.canvas; 3161 let rect: common2D.Rect = { left: 10, top: 100, right: 200, bottom: 300 }; 3162 let roundRect = new drawing.RoundRect(rect, 10, 10); 3163 canvas.clipRoundRect(roundRect); 3164 } 3165} 3166``` 3167 3168### resetMatrix<sup>12+</sup> 3169 3170resetMatrix(): void 3171 3172Resets the matrix of this canvas to an identity matrix. 3173 3174**System capability**: SystemCapability.Graphics.Drawing 3175 3176**Example** 3177 3178```ts 3179import { RenderNode } from '@kit.ArkUI'; 3180import { drawing } from '@kit.ArkGraphics2D'; 3181class DrawingRenderNode extends RenderNode { 3182 draw(context : DrawContext) { 3183 const canvas = context.canvas; 3184 canvas.scale(4, 6); 3185 canvas.resetMatrix(); 3186 } 3187} 3188``` 3189 3190## ImageFilter<sup>12+</sup> 3191 3192Implements an image filter. 3193 3194### createBlurImageFilter<sup>12+</sup> 3195 3196static createBlurImageFilter(sigmaX: number, sigmaY: number, tileMode: TileMode, imageFilter?: ImageFilter | null ): ImageFilter 3197 3198Creates an image filter with a given blur effect. 3199 3200**System capability**: SystemCapability.Graphics.Drawing 3201 3202**Parameters** 3203 3204| Name | Type | Mandatory| Description | 3205| --------------- | ------- | ---- | ----------------------------------------------------------- | 3206| sigmaX | number | Yes | Standard deviation of the Gaussian blur along the X axis. The value must be a floating point number greater than 0.| 3207| sigmaY | number | Yes | Standard deviation of the Gaussian blur along the Y axis. The value must be a floating point number greater than 0.| 3208| tileMode | [TileMode](#tilemode12)| Yes | Tile mode to apply to the edges.| 3209| imageFilter | [ImageFilter](#imagefilter12) \| null | No | Filter to which the image filter will be applied. The default value is null, indicating that the image filter is directly applied to the original image.| 3210 3211**Return value** 3212 3213| Type | Description | 3214| --------------------- | -------------- | 3215| [ImageFilter](#imagefilter12) | Image filter created.| 3216 3217**Error codes** 3218 3219For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3220 3221| ID| Error Message| 3222| ------- | --------------------------------------------| 3223| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 3224 3225**Example** 3226 3227```ts 3228import { drawing } from '@kit.ArkGraphics2D'; 3229let imgFilter = drawing.ImageFilter.createBlurImageFilter(5, 10, drawing.TileMode.CLAMP); 3230``` 3231 3232### createFromColorFilter<sup>12+</sup> 3233 3234static createFromColorFilter(colorFilter: ColorFilter, imageFilter?: ImageFilter | null): ImageFilter 3235 3236Creates an image filter object with a given color filter effect. 3237 3238**System capability**: SystemCapability.Graphics.Drawing 3239 3240**Parameters** 3241 3242| Name | Type | Mandatory| Description | 3243| --------------- | ------- | ---- | ----------------------------------------------------------- | 3244| colorFilter | [ColorFilter](#colorfilter) | Yes | Color filter.| 3245| imageFilter | [ImageFilter](#imagefilter12) \| null | No | Filter to which the image filter will be applied. The default value is null, indicating that the image filter is directly applied to the original image.| 3246 3247**Return value** 3248 3249| Type | Description | 3250| --------------------- | -------------- | 3251| [ImageFilter](#imagefilter12) | Image filter created.| 3252 3253**Error codes** 3254 3255For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3256 3257| ID| Error Message| 3258| ------- | --------------------------------------------| 3259| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3260 3261**Example** 3262 3263```ts 3264import { drawing } from '@kit.ArkGraphics2D'; 3265let imgFilter = drawing.ImageFilter.createBlurImageFilter(5, 10, drawing.TileMode.CLAMP); 3266let clolorfilter = drawing.ColorFilter.createSRGBGammaToLinear(); 3267let imgFilter1 = drawing.ImageFilter.createFromColorFilter(clolorfilter, imgFilter); 3268``` 3269 3270## TextBlobRunBuffer 3271 3272Describes a series of consecutive glyphs with the same attributes in a text blob. 3273 3274**System capability**: SystemCapability.Graphics.Drawing 3275 3276| Name | Type | Readable| Writable| Description | 3277| --------- | ------ | ---- | ---- | ------------------------- | 3278| glyph | number | Yes | Yes | Index of the glyph. The value is an integer. If a floating point number is passed in, the value is rounded down.| 3279| positionX | number | Yes | Yes | X coordinate of the start point of the text blob. The value is a floating point number.| 3280| positionY | number | Yes | Yes | Y coordinate of the start point of the text blob. The value is a floating point number.| 3281 3282## TextEncoding 3283 3284Enumerates the text encoding types. 3285 3286**System capability**: SystemCapability.Graphics.Drawing 3287 3288| Name | Value | Description | 3289| ---------------------- | ---- | ------------------------------ | 3290| TEXT_ENCODING_UTF8 | 0 | One byte is used to indicate UTF-8 or ASCII characters. | 3291| TEXT_ENCODING_UTF16 | 1 | Two bytes are used to indicate most Unicode characters.| 3292| TEXT_ENCODING_UTF32 | 2 | Four bytes are used to indicate all Unicode characters. | 3293| TEXT_ENCODING_GLYPH_ID | 3 | Two bytes are used to indicate the glyph index. | 3294 3295## ClipOp<sup>12+</sup> 3296Enumerates the canvas clipping modes. 3297 3298 3299**System capability**: SystemCapability.Graphics.Drawing 3300 3301| Name | Value | Description | Diagram | 3302| ------------------ | ---- | ---------------- | -------- | 3303| DIFFERENCE | 0 | Clips a specified area. That is, the difference set is obtained.|  | 3304| INTERSECT | 1 | Retains a specified area. That is, the intersection is obtained.|  | 3305 3306> **NOTE** 3307> 3308> The diagrams show the result of cropping a circle based on different enumerated values after a rectangle is cropped in INTERSECT mode. The green area is the final area obtained. 3309 3310## FilterMode<sup>12+</sup> 3311 3312Enumerates the filter modes. 3313 3314**System capability**: SystemCapability.Graphics.Drawing 3315 3316| Name | Value | Description | 3317| ------------------- | ---- | ------- | 3318| FILTER_MODE_NEAREST | 0 | Nearest filter mode.| 3319| FILTER_MODE_LINEAR | 1 | Linear filter mode.| 3320 3321## PathDirection<sup>12+</sup> 3322 3323Enumerates the directions of a closed contour. 3324 3325**System capability**: SystemCapability.Graphics.Drawing 3326 3327| Name | Value | Description | 3328| ------------------- | ---- | ------- | 3329| CLOCKWISE | 0 | Adds a closed contour clockwise.| 3330| COUNTER_CLOCKWISE | 1 | Adds a closed contour counterclockwise.| 3331 3332## PathFillType<sup>12+</sup> 3333 3334Enumerates the fill types of a path. 3335 3336**System capability**: SystemCapability.Graphics.Drawing 3337 3338| Name | Value | Description | 3339| ------------------- | ---- | ------- | 3340| WINDING | 0 | Specifies that "inside" is computed by a non-zero sum of signed edge crossings. Specifically, draws a point and emits a ray in any direction. A count is used to record the number of intersection points of the ray and path, and the initial count is 0. When encountering a clockwise intersection point (the path passes from the left to the right of the ray), the count increases by 1. When encountering a counterclockwise intersection point (the path passes from the right to the left of the ray), the count decreases by 1. If the final count is not 0, the point is inside the path and needs to be colored. If the final count is 0, the point is not colored.| 3341| EVEN_ODD | 1 | Specifies that "inside" is computed by an odd number of edge crossings. Specifically, draws a point and emits a ray in any direction. If the number of intersection points of the ray and path is an odd number, the point is considered to be inside the path and needs to be colored. If the number is an even number, the point is not colored.| 3342| INVERSE_WINDING | 2 | Same as **WINDING**, but draws outside of the path, rather than inside.| 3343| INVERSE_EVEN_ODD | 3 | Same as **EVEN_ODD**, but draws outside of the path, rather than inside.| 3344 3345> **NOTE** 3346>  3347> As shown in the above figure, the path is a circle, the arrow indicates the path direction, **p** is any point "inside" the path, the blue line is the ray emitted from **p**, and the black arrow indicates the fill result using blue under the corresponding fill type. Under the **WINDING** fill rule, the number of intersection points of the ray and path is 2 (not 0), and therefore **p** is colored. Under the **EVEN_ODD** filling rule, the number of intersection points of the ray and path is 2 (an even number), and therefore **p** is not colored. 3348 3349## PointMode<sup>12+</sup> 3350 3351Enumerates the modes for drawing multiple points in an array. 3352 3353**System capability**: SystemCapability.Graphics.Drawing 3354 3355| Name | Value | Description | 3356| ------------------ | ---- | ------------- | 3357| POINTS | 0 | Draws each point separately. | 3358| LINES | 1 | Draws every two points as a line segment. | 3359| POLYGON | 2 | Draws an array of points as an open polygon.| 3360 3361## FontEdging<sup>12+</sup> 3362 3363Enumerates the font edging types. 3364 3365**System capability**: SystemCapability.Graphics.Drawing 3366 3367| Name | Value | Description | 3368| ------------------- | ---- | ------- | 3369| ALIAS | 0 | No anti-aliasing processing is used.| 3370| ANTI_ALIAS | 1 | Uses anti-aliasing to smooth the jagged edges.| 3371| SUBPIXEL_ANTI_ALIAS | 2 | Uses sub-pixel anti-aliasing to provide a smoother effect for jagged edges.| 3372 3373## FontHinting<sup>12+</sup> 3374 3375Enumerates the font hinting types. 3376 3377**System capability**: SystemCapability.Graphics.Drawing 3378 3379| Name | Value | Description | 3380| ------------------- | ---- | ------- | 3381| NONE | 0 | No font hinting is used.| 3382| SLIGHT | 1 | Slight font hinting is used to improve contrast.| 3383| NORMAL | 2 | Normal font hinting is used to improve contrast.| 3384| FULL | 3 | Full font hinting is used to improve contrast.| 3385 3386## TextBlob 3387 3388Defines a block consisting of one or more characters with the same font. 3389 3390### makeFromPosText<sup>12+</sup> 3391 3392static makeFromPosText(text: string, len: number, points: common2D.Point[], font: Font): TextBlob 3393 3394Creates a **TextBlob** object from the text. The coordinates of each font in the **TextBlob** object are determined by the coordinate information in the **points** array. 3395 3396**System capability**: SystemCapability.Graphics.Drawing 3397 3398**Parameters** 3399 3400| Name | Type | Mandatory| Description | 3401| -------- | ----------------------------- | ---- | -------------------------------------- | 3402| text | string | Yes | Content to be used for drawing the text blob. | 3403| len | number | Yes | Number of fonts. The value is an integer and is obtained from [countText](#counttext12).| 3404| points |[common2D.Point](js-apis-graphics-common2D.md#point)[] | Yes |Array of points, which are used to specify the coordinates of each font. The array length must be the same as the value of **len**.| 3405| font | [Font](#font) | Yes | **Font** object.| 3406 3407**Return value** 3408 3409| Type | Description | 3410| --------------------- | -------------- | 3411| [TextBlob](#textblob) | **TextBlob** object.| 3412 3413 3414**Error codes** 3415 3416For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3417 3418| ID| Error Message| 3419| ------- | --------------------------------------------| 3420| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types. | 3421 3422**Example** 3423 3424```ts 3425import { RenderNode } from '@kit.ArkUI'; 3426import { drawing,common2D} from '@kit.ArkGraphics2D'; 3427 3428class DrawingRenderNode extends RenderNode { 3429 draw(context : DrawContext) { 3430 const canvas = context.canvas; 3431 let text : string = 'makeFromPosText'; 3432 let font : drawing.Font = new drawing.Font(); 3433 font.setSize(100); 3434 let length = font.countText(text); 3435 let points : common2D.Point[] = []; 3436 for (let i = 0; i !== length; ++i) { 3437 points.push({ x: i * 35, y: i * 35 }); 3438 } 3439 let textblob : drawing.TextBlob =drawing.TextBlob.makeFromPosText(text, points.length, points, font); 3440 canvas.drawTextBlob(textblob, 100, 100); 3441 } 3442} 3443``` 3444 3445### uniqueID<sup>12+</sup> 3446 3447uniqueID(): number 3448 3449Obtains the unique identifier of a text blob. The identifier is a non-zero value. 3450 3451**System capability**: SystemCapability.Graphics.Drawing 3452 3453**Return value** 3454 3455| Type | Description | 3456| --------------------- | -------------- | 3457| number | Unique identifier of the text blob.| 3458 3459**Example** 3460 3461```ts 3462import {drawing} from "@kit.ArkGraphics2D" 3463let text : string = 'TextBlobUniqueId'; 3464let font : drawing.Font = new drawing.Font(); 3465font.setSize(100); 3466let textBlob = drawing.TextBlob.makeFromString(text, font, 0); 3467let id = textBlob.uniqueID(); 3468console.info("uniqueID---------------" +id); 3469``` 3470 3471### makeFromString 3472 3473static makeFromString(text: string, font: Font, encoding?: TextEncoding): TextBlob 3474 3475Converts a value of the string type into a **TextBlob** object. 3476 3477**System capability**: SystemCapability.Graphics.Drawing 3478 3479**Parameters** 3480 3481| Name | Type | Mandatory| Description | 3482| -------- | ----------------------------- | ---- | -------------------------------------- | 3483| text | string | Yes | Content to be used for drawing the text blob. | 3484| font | [Font](#font) | Yes | **Font** object. | 3485| encoding | [TextEncoding](#textencoding) | No | Encoding type. The default value is **TEXT_ENCODING_UTF8**. Currently, only **TEXT_ENCODING_UTF8** takes effect, and other encoding types are treated as **TEXT_ENCODING_UTF8**.| 3486 3487**Return value** 3488 3489| Type | Description | 3490| --------------------- | -------------- | 3491| [TextBlob](#textblob) | **TextBlob** object.| 3492 3493**Error codes** 3494 3495For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3496 3497| ID| Error Message| 3498| ------- | --------------------------------------------| 3499| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3500 3501**Example** 3502 3503```ts 3504import { RenderNode } from '@kit.ArkUI'; 3505import { drawing } from '@kit.ArkGraphics2D'; 3506class DrawingRenderNode extends RenderNode { 3507 draw(context : DrawContext) { 3508 const canvas = context.canvas; 3509 const brush = new drawing.Brush(); 3510 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 3511 const font = new drawing.Font(); 3512 font.setSize(20); 3513 const textBlob = drawing.TextBlob.makeFromString("drawing", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 3514 canvas.attachBrush(brush); 3515 canvas.drawTextBlob(textBlob, 20, 20); 3516 canvas.detachBrush(); 3517 } 3518} 3519``` 3520 3521### makeFromRunBuffer 3522 3523static makeFromRunBuffer(pos: Array\<TextBlobRunBuffer>, font: Font, bounds?: common2D.Rect): TextBlob 3524 3525Creates a **Textblob** object based on the RunBuffer information. 3526 3527**System capability**: SystemCapability.Graphics.Drawing 3528 3529**Parameters** 3530 3531| Name| Type | Mandatory| Description | 3532| ------ | -------------------------------------------------- | ---- | ------------------------------ | 3533| pos | Array\<[TextBlobRunBuffer](#textblobrunbuffer)> | Yes | **TextBlobRunBuffer** array. | 3534| font | [Font](#font) | Yes | **Font** object. | 3535| bounds | [common2D.Rect](js-apis-graphics-common2D.md#rect) | No | Bounding box. If this parameter is not set, there is no bounding box.| 3536 3537**Return value** 3538 3539| Type | Description | 3540| --------------------- | -------------- | 3541| [TextBlob](#textblob) | **TextBlob** object.| 3542 3543**Error codes** 3544 3545For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3546 3547| ID| Error Message| 3548| ------- | --------------------------------------------| 3549| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3550 3551**Example** 3552 3553```ts 3554import { RenderNode } from '@kit.ArkUI'; 3555import { common2D, drawing } from '@kit.ArkGraphics2D'; 3556class DrawingRenderNode extends RenderNode { 3557 draw(context : DrawContext) { 3558 const canvas = context.canvas; 3559 const font = new drawing.Font(); 3560 font.setSize(20); 3561 let runBuffer : Array<drawing.TextBlobRunBuffer> = [ 3562 { glyph: 65, positionX: 0, positionY: 0 }, 3563 { glyph: 227, positionX: 14.9, positionY: 0 }, 3564 { glyph: 283, positionX: 25.84, positionY: 0 }, 3565 { glyph: 283, positionX: 30.62, positionY: 0 }, 3566 { glyph: 299, positionX: 35.4, positionY: 0} 3567 ]; 3568 const textBlob = drawing.TextBlob.makeFromRunBuffer(runBuffer, font, null); 3569 const brush = new drawing.Brush(); 3570 brush.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 3571 canvas.attachBrush(brush); 3572 canvas.drawTextBlob(textBlob, 20, 20); 3573 canvas.detachBrush(); 3574 } 3575} 3576``` 3577 3578### bounds 3579 3580bounds(): common2D.Rect 3581 3582Obtains the rectangular bounding box of the text blob. 3583 3584**System capability**: SystemCapability.Graphics.Drawing 3585 3586**Return value** 3587 3588| Type | Description | 3589| -------------------------------------------------- | ---------------------- | 3590| [common2D.Rect](js-apis-graphics-common2D.md#rect) | Rectangular bounding box.| 3591 3592**Example** 3593 3594```ts 3595import { common2D, drawing } from '@kit.ArkGraphics2D'; 3596const font = new drawing.Font(); 3597font.setSize(20); 3598const textBlob = drawing.TextBlob.makeFromString("drawing", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 3599let bounds = textBlob.bounds(); 3600``` 3601 3602## Typeface 3603 3604Describes the typeface such as SimSun and Kaiti. 3605 3606### getFamilyName 3607 3608getFamilyName(): string 3609 3610Obtains the name of the typeface, that is, the name of the font family. 3611 3612**System capability**: SystemCapability.Graphics.Drawing 3613 3614**Return value** 3615 3616| Type | Description | 3617| ------ | -------------------- | 3618| string | Typeface name.| 3619 3620**Example** 3621 3622```ts 3623import { drawing } from '@kit.ArkGraphics2D'; 3624const font = new drawing.Font(); 3625let typeface = font.getTypeface(); 3626let familyName = typeface.getFamilyName(); 3627``` 3628 3629### makeFromFile<sup>12+</sup> 3630 3631static makeFromFile(filePath: string): Typeface 3632 3633Constructs a typeface from a file. 3634 3635**System capability**: SystemCapability.Graphics.Drawing 3636 3637**Parameters** 3638 3639| Name | Type | Mandatory | Description | 3640| ----------- | ---------------------------------------- | ---- | ------------------- | 3641| filePath | string | Yes | Path of the file. For details, see [Mappings Between Application Sandbox Paths and Physical Paths](../../file-management/app-sandbox-directory.md#mappings-between-application-sandbox-paths-and-physical-paths).| 3642 3643**Return value** 3644 3645| Type | Description | 3646| ------ | -------------------- | 3647| [Typeface](#typeface) | **Typeface** object.| 3648 3649**Error codes** 3650 3651For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3652 3653| ID| Error Message| 3654| ------- | --------------------------------------------| 3655| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3656 3657**Example** 3658 3659```ts 3660import { RenderNode } from '@kit.ArkUI'; 3661import { drawing } from '@kit.ArkGraphics2D'; 3662class TextRenderNode extends RenderNode { 3663 async draw(context: DrawContext) { 3664 const canvas = context.canvas; 3665 let font = new drawing.Font(); 3666 let str = "/system/fonts/HarmonyOS_Sans_Italic.ttf"; 3667 const mytypeface = drawing.Typeface.makeFromFile(str); 3668 font.setTypeface(mytypeface); 3669 const textBlob = drawing.TextBlob.makeFromString("Hello World", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 3670 canvas.drawTextBlob(textBlob, 60, 100); 3671 } 3672} 3673``` 3674 3675## Font 3676 3677Describes the attributes, such as the size, used for drawing text. 3678 3679### isSubpixel<sup>12+</sup> 3680 3681isSubpixel(): boolean 3682 3683Checks whether sub-pixel rendering is used for this font. 3684 3685**System capability**: SystemCapability.Graphics.Drawing 3686 3687**Return value** 3688 3689| Type | Description | 3690| ------ | -------------------- | 3691| boolean | Check result. The value **true** means that sub-pixel rendering is used, and **false** means the opposite.| 3692 3693**Example** 3694 3695```ts 3696import {drawing} from '@kit.ArkGraphics2D'; 3697let font: drawing.Font = new drawing.Font(); 3698font.enableSubpixel(true) 3699console.info("values=" + font.isSubpixel()); 3700``` 3701 3702### isLinearMetrics<sup>12+</sup> 3703 3704isLinearMetrics(): boolean 3705 3706Checks whether linear scaling is used for this font. 3707 3708**System capability**: SystemCapability.Graphics.Drawing 3709 3710**Return value** 3711 3712| Type | Description | 3713| ------ | -------------------- | 3714| boolean | Check result. The value **true** means that linear scaling is used, and **false** means the opposite.| 3715 3716**Example** 3717 3718```ts 3719import {drawing} from '@kit.ArkGraphics2D'; 3720let font: drawing.Font = new drawing.Font(); 3721font.enableLinearMetrics(true) 3722console.info("values=" + font.isLinearMetrics()); 3723``` 3724 3725### getSkewX<sup>12+</sup> 3726 3727getSkewX(): number 3728 3729Obtains the horizontal skew factor of this font. 3730 3731**System capability**: SystemCapability.Graphics.Drawing 3732 3733**Return value** 3734 3735| Type | Description | 3736| ------ | -------------------- | 3737| number | Horizontal skew factor.| 3738 3739**Example** 3740 3741```ts 3742import {drawing} from '@kit.ArkGraphics2D'; 3743let font: drawing.Font = new drawing.Font(); 3744font.setSkewX(-1) 3745console.info("values=" + font.getSkewX()); 3746``` 3747 3748### isEmbolden<sup>12+</sup> 3749 3750isEmbolden(): boolean 3751 3752Checks whether the bold effect is set for this font. 3753 3754**System capability**: SystemCapability.Graphics.Drawing 3755 3756**Return value** 3757 3758| Type | Description | 3759| ------ | -------------------- | 3760| boolean | Check result. The value **true** means that the bold effect is set, and **false** means the opposite.| 3761 3762**Example** 3763 3764```ts 3765import {drawing} from '@kit.ArkGraphics2D'; 3766let font: drawing.Font = new drawing.Font(); 3767font.enableEmbolden(true); 3768console.info("values=" + font.isEmbolden()); 3769``` 3770 3771### getScaleX<sup>12+</sup> 3772 3773getScaleX(): number 3774 3775Obtains the horizontal scale ratio of this font. 3776 3777**System capability**: SystemCapability.Graphics.Drawing 3778 3779**Return value** 3780 3781| Type | Description | 3782| ------ | -------------------- | 3783| number | Horizontal scale ratio.| 3784 3785**Example** 3786 3787```ts 3788import {drawing} from '@kit.ArkGraphics2D'; 3789let font: drawing.Font = new drawing.Font(); 3790font.setScaleX(2); 3791console.info("values=" + font.getScaleX()); 3792``` 3793 3794### getHinting<sup>12+</sup> 3795 3796getHinting(): FontHinting 3797 3798Obtains the font hinting effect. 3799 3800**System capability**: SystemCapability.Graphics.Drawing 3801 3802**Return value** 3803 3804| Type | Description | 3805| ------ | -------------------- | 3806| [FontHinting](#fonthinting12) | Font hinting effect.| 3807 3808**Example** 3809 3810```ts 3811import {drawing} from '@kit.ArkGraphics2D'; 3812let font: drawing.Font = new drawing.Font(); 3813console.info("values=" + font.getHinting()); 3814``` 3815 3816### getEdging<sup>12+</sup> 3817 3818getEdging(): FontEdging 3819 3820Obtains the font edging effect. 3821 3822**System capability**: SystemCapability.Graphics.Drawing 3823 3824**Return value** 3825 3826| Type | Description | 3827| ------ | -------------------- | 3828| [FontEdging](#fontedging12) | Font edging effect.| 3829 3830**Example** 3831 3832```ts 3833import {drawing} from '@kit.ArkGraphics2D'; 3834let font: drawing.Font = new drawing.Font(); 3835console.info("values=" + font.getEdging()); 3836``` 3837 3838### enableSubpixel 3839 3840enableSubpixel(isSubpixel: boolean): void 3841 3842Enables subpixel font rendering. 3843 3844**System capability**: SystemCapability.Graphics.Drawing 3845 3846**Parameters** 3847 3848| Name | Type | Mandatory| Description | 3849| ---------- | ------- | ---- | ------------------------------------------------------------ | 3850| isSubpixel | boolean | Yes | Whether to enable subpixel font rendering. The value **true** means to enable subpixel font rendering, and **false** means the opposite.| 3851 3852**Error codes** 3853 3854For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3855 3856| ID| Error Message| 3857| ------- | --------------------------------------------| 3858| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3859 3860**Example** 3861 3862```ts 3863import { drawing } from '@kit.ArkGraphics2D'; 3864let font = new drawing.Font(); 3865font.enableSubpixel(true); 3866``` 3867 3868### enableEmbolden 3869 3870enableEmbolden(isEmbolden: boolean): void 3871 3872Enables emboldened fonts. 3873 3874**System capability**: SystemCapability.Graphics.Drawing 3875 3876**Parameters** 3877 3878| Name | Type | Mandatory| Description | 3879| ---------- | ------- | ---- | ----------------------------------------------------- | 3880| isEmbolden | boolean | Yes | Whether to enable emboldened fonts. The value **true** means to enable emboldened fonts, and **false** means the opposite.| 3881 3882**Error codes** 3883 3884For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3885 3886| ID| Error Message| 3887| ------- | --------------------------------------------| 3888| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3889 3890**Example** 3891 3892```ts 3893import { drawing } from '@kit.ArkGraphics2D'; 3894let font = new drawing.Font(); 3895font.enableEmbolden(true); 3896``` 3897 3898### enableLinearMetrics 3899 3900enableLinearMetrics(isLinearMetrics: boolean): void 3901 3902Enables linear font scaling. 3903 3904**System capability**: SystemCapability.Graphics.Drawing 3905 3906**Parameters** 3907 3908| Name | Type | Mandatory| Description | 3909| --------------- | ------- | ---- | ----------------------------------------------------------- | 3910| isLinearMetrics | boolean | Yes | Whether to enable linear font scaling. The value **true** means to enable linear font scaling, and **false** means the opposite.| 3911 3912**Error codes** 3913 3914For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3915 3916| ID| Error Message| 3917| ------- | --------------------------------------------| 3918| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 3919 3920**Example** 3921 3922```ts 3923import { drawing } from '@kit.ArkGraphics2D'; 3924let font = new drawing.Font(); 3925font.enableLinearMetrics(true); 3926``` 3927 3928### setSize 3929 3930setSize(textSize: number): void 3931 3932Sets the text size. 3933 3934**System capability**: SystemCapability.Graphics.Drawing 3935 3936**Parameters** 3937 3938| Name | Type | Mandatory| Description | 3939| -------- | ------ | ---- | ---------------- | 3940| textSize | number | Yes | Text size. The value is a floating point number. If a negative number is passed in, the size is set to 0. If the size is 0, the text drawn will not be displayed.| 3941 3942**Error codes** 3943 3944For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3945 3946| ID| Error Message| 3947| ------- | --------------------------------------------| 3948| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 3949 3950**Example** 3951 3952```ts 3953import { drawing } from '@kit.ArkGraphics2D'; 3954let font = new drawing.Font(); 3955font.setSize(5); 3956``` 3957 3958### getSize 3959 3960getSize(): number 3961 3962Obtains the text size. 3963 3964**System capability**: SystemCapability.Graphics.Drawing 3965 3966**Return value** 3967 3968| Type | Description | 3969| ------ | ---------------- | 3970| number | Text size. The value is a floating point number.| 3971 3972**Example** 3973 3974```ts 3975import { drawing } from '@kit.ArkGraphics2D'; 3976let font = new drawing.Font(); 3977font.setSize(5); 3978let fontSize = font.getSize(); 3979``` 3980 3981### setTypeface 3982 3983setTypeface(typeface: Typeface): void 3984 3985Sets the typeface. 3986 3987**System capability**: SystemCapability.Graphics.Drawing 3988 3989**Parameters** 3990 3991| Name | Type | Mandatory| Description | 3992| -------- | --------------------- | ---- | ------ | 3993| typeface | [Typeface](#typeface) | Yes | **Typeface** object.| 3994 3995**Error codes** 3996 3997For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3998 3999| ID| Error Message| 4000| ------- | --------------------------------------------| 4001| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4002 4003**Example** 4004 4005```ts 4006import { drawing } from '@kit.ArkGraphics2D'; 4007let font = new drawing.Font(); 4008font.setTypeface(new drawing.Typeface()); 4009``` 4010 4011### getTypeface 4012 4013getTypeface(): Typeface 4014 4015Obtains the typeface. 4016 4017**System capability**: SystemCapability.Graphics.Drawing 4018 4019**Return value** 4020 4021| Type | Description | 4022| --------------------- | ------ | 4023| [Typeface](#typeface) | **Typeface** object.| 4024 4025**Example** 4026 4027```ts 4028import { drawing } from '@kit.ArkGraphics2D'; 4029let font = new drawing.Font(); 4030let typeface = font.getTypeface(); 4031``` 4032 4033### getMetrics 4034 4035getMetrics(): FontMetrics 4036 4037Obtains the font metrics of the typeface. 4038 4039**System capability**: SystemCapability.Graphics.Drawing 4040 4041**Return value** 4042 4043| Type | Description | 4044| --------------------------- | ----------------- | 4045| [FontMetrics](#fontmetrics) | Font metrics.| 4046 4047**Example** 4048 4049```ts 4050import { drawing } from '@kit.ArkGraphics2D'; 4051let font = new drawing.Font(); 4052let metrics = font.getMetrics(); 4053``` 4054 4055### measureText 4056 4057measureText(text: string, encoding: TextEncoding): number 4058 4059Measures the text width. 4060 4061> **NOTE** 4062> 4063> This API is used to measure the text width of the original string. To measure the text width after typesetting, call [measure.measureText](../apis-arkui/js-apis-measure.md#measuretextmeasuretext). 4064 4065**System capability**: SystemCapability.Graphics.Drawing 4066 4067**Parameters** 4068 4069| Name | Type | Mandatory| Description | 4070| -------- | ----------------------------- | ---- | ---------- | 4071| text | string | Yes | Text content.| 4072| encoding | [TextEncoding](#textencoding) | Yes | Encoding format.| 4073 4074**Return value** 4075 4076| Type | Description | 4077| ------ | ---------------- | 4078| number | Width of the text. The value is a floating point number.| 4079 4080**Error codes** 4081 4082For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4083 4084| ID| Error Message| 4085| ------- | --------------------------------------------| 4086| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4087 4088**Example** 4089 4090```ts 4091import { drawing } from '@kit.ArkGraphics2D'; 4092let font = new drawing.Font(); 4093font.measureText("drawing", drawing.TextEncoding.TEXT_ENCODING_UTF8); 4094``` 4095 4096### measureSingleCharacter<sup>12+</sup> 4097 4098measureSingleCharacter(text: string): number 4099 4100Measures the width of a single character. If the typeface of the current font does not support the character to measure, the system typeface is used to measure the character width. 4101 4102**System capability**: SystemCapability.Graphics.Drawing 4103 4104**Parameters** 4105 4106| Name| Type | Mandatory| Description | 4107| ------ | ------------------- | ---- | ----------- | 4108| text | string | Yes | Single character to measure. The length of the string must be 1. | 4109 4110**Return value** 4111 4112| Type | Description | 4113| ------ | ---------------- | 4114| number | Width of the character. The value is a floating point number.| 4115 4116**Error codes** 4117 4118For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4119 4120| ID| Error Message| 4121| ------- | --------------------------------------------| 4122| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 4123 4124**Example** 4125 4126```ts 4127import { RenderNode } from '@kit.ArkUI'; 4128import { drawing } from '@kit.ArkGraphics2D'; 4129 4130class DrawingRenderNode extends RenderNode { 4131 draw(context : DrawContext) { 4132 const canvas = context.canvas; 4133 const font = new drawing.Font(); 4134 font.setSize(20); 4135 let width = font.measureSingleCharacter ("Hello"); 4136 } 4137} 4138``` 4139 4140### setScaleX<sup>12+</sup> 4141 4142setScaleX(scaleX: number): void 4143 4144Sets a horizontal scale factor for this font. 4145 4146**System capability**: SystemCapability.Graphics.Drawing 4147 4148**Parameters** 4149 4150| Name | Type | Mandatory| Description | 4151| -------- | ----------------------------- | ---- | ---------- | 4152| scaleX | number | Yes | Horizontal scale factor. The value is a floating point number.| 4153 4154**Error codes** 4155 4156For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4157 4158| ID| Error Message| 4159| ------- | --------------------------------------------| 4160| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4161 4162**Example** 4163 4164```ts 4165import { RenderNode } from '@kit.ArkUI'; 4166import { common2D, drawing } from '@kit.ArkGraphics2D'; 4167class DrawingRenderNode extends RenderNode { 4168 draw(context : DrawContext) { 4169 const canvas = context.canvas; 4170 const pen = new drawing.Pen(); 4171 pen.setStrokeWidth(5); 4172 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 4173 canvas.attachPen(pen); 4174 let font = new drawing.Font(); 4175 font.setSize(100); 4176 font.setScaleX(2); 4177 const textBlob = drawing.TextBlob.makeFromString("hello", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 4178 canvas.drawTextBlob(textBlob, 200, 200); 4179 } 4180} 4181``` 4182 4183### setSkewX<sup>12+</sup> 4184 4185setSkewX(skewX: number): void 4186 4187Sets a horizontal skew factor for this font. 4188 4189**System capability**: SystemCapability.Graphics.Drawing 4190 4191**Parameters** 4192 4193| Name | Type | Mandatory| Description | 4194| -------- | ----------------------------- | ---- | ---------- | 4195| skewX | number | Yes | Horizontal skew factor. A positive number means a skew to the left, and a negative number means a skew to the right. The value is a floating point number.| 4196 4197**Error codes** 4198 4199For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4200 4201| ID| Error Message| 4202| ------- | --------------------------------------------| 4203| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4204 4205**Example** 4206 4207```ts 4208import { RenderNode } from '@kit.ArkUI'; 4209import { common2D, drawing } from '@kit.ArkGraphics2D'; 4210class DrawingRenderNode extends RenderNode { 4211 draw(context : DrawContext) { 4212 const canvas = context.canvas; 4213 const pen = new drawing.Pen(); 4214 pen.setStrokeWidth(5); 4215 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 4216 canvas.attachPen(pen); 4217 let font = new drawing.Font(); 4218 font.setSize(100); 4219 font.setSkewX(1); 4220 const textBlob = drawing.TextBlob.makeFromString("hello", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 4221 canvas.drawTextBlob(textBlob, 200, 200); 4222 } 4223} 4224``` 4225 4226### setEdging<sup>12+</sup> 4227 4228setEdging(edging: FontEdging): void 4229 4230Sets a font edging effect. 4231 4232**System capability**: SystemCapability.Graphics.Drawing 4233 4234**Parameters** 4235 4236| Name | Type | Mandatory| Description | 4237| -------- | ----------------------------- | ---- | ---------- | 4238| edging | [FontEdging](#fontedging12) | Yes | Font edging effect.| 4239 4240**Error codes** 4241 4242For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4243 4244| ID| Error Message| 4245| ------- | --------------------------------------------| 4246| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 4247 4248**Example** 4249 4250```ts 4251import { drawing } from '@kit.ArkGraphics2D'; 4252 4253let font = new drawing.Font(); 4254font.setEdging(drawing.FontEdging.SUBPIXEL_ANTI_ALIAS); 4255``` 4256 4257### setHinting<sup>12+</sup> 4258 4259setHinting(hinting: FontHinting): void 4260 4261Sets a font hinting effect. 4262 4263**System capability**: SystemCapability.Graphics.Drawing 4264 4265**Parameters** 4266 4267| Name | Type | Mandatory| Description | 4268| -------- | ----------------------------- | ---- | ---------- | 4269| hinting | [FontHinting](#fonthinting12) | Yes | Font hinting effect.| 4270 4271**Error codes** 4272 4273For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4274 4275| ID| Error Message| 4276| ------- | --------------------------------------------| 4277| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 4278 4279**Example** 4280 4281```ts 4282import { drawing } from '@kit.ArkGraphics2D'; 4283 4284let font = new drawing.Font(); 4285font.setHinting(drawing.FontHinting.FULL); 4286``` 4287 4288### countText<sup>12+</sup> 4289 4290countText(text: string): number 4291 4292Obtains the number of glyphs represented by text. 4293 4294**System capability**: SystemCapability.Graphics.Drawing 4295 4296**Parameters** 4297 4298| Name | Type | Mandatory| Description | 4299| -------- | ----------------------------- | ---- | ---------- | 4300| text | string | Yes | Text content.| 4301 4302**Return value** 4303 4304| Type | Description | 4305| ------ | ---------------- | 4306| number | Number of glyphs represented by the text. The value is an integer.| 4307 4308**Error codes** 4309 4310For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4311 4312| ID| Error Message| 4313| ------- | --------------------------------------------| 4314| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4315 4316**Example** 4317 4318```ts 4319import { drawing } from '@kit.ArkGraphics2D'; 4320 4321let font = new drawing.Font(); 4322let resultNumber: number = font.countText('ABCDE'); 4323console.info("count text number: " + resultNumber); 4324``` 4325 4326### setBaselineSnap<sup>12+</sup> 4327 4328setBaselineSnap(isBaselineSnap: boolean): void 4329 4330Sets whether to request that baselines be snapped to pixels when the current canvas matrix is axis aligned. 4331 4332**System capability**: SystemCapability.Graphics.Drawing 4333 4334**Parameters** 4335 4336| Name | Type | Mandatory| Description | 4337| --------------- | ------- | ---- | ---------------------------------------- | 4338| isBaselineSnap | boolean | Yes | Whether to request that baselines be snapped to pixels. The value **true** means to request that baselines be snapped to pixels, and **false** means the opposite.| 4339 4340**Error codes** 4341 4342For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4343 4344| ID| Error Message| 4345| ------- | --------------------------------------------| 4346| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4347 4348**Example** 4349 4350```ts 4351import { drawing } from '@kit.ArkGraphics2D'; 4352 4353let font : drawing.Font = new drawing.Font(); 4354font.setBaselineSnap(true); 4355console.info("drawing font isBaselineSnap: " + font.isBaselineSnap()); 4356``` 4357 4358### isBaselineSnap()<sup>12+</sup> 4359 4360isBaselineSnap(): boolean 4361 4362Checks whether baselines are requested to be snapped to pixels when the current canvas matrix is axis aligned. 4363 4364**System capability**: SystemCapability.Graphics.Drawing 4365 4366**Return value** 4367 4368| Type | Description | 4369| ------ | ---------------- | 4370| boolean | Result indicating whether the baselines are requested to be snapped to pixels when the current canvas matrix is axis aligned. The value **true** means that the baselines are requested to be snapped to pixels, and **false** means the opposite.| 4371 4372**Example** 4373 4374```ts 4375import { drawing } from '@kit.ArkGraphics2D'; 4376 4377let font : drawing.Font = new drawing.Font(); 4378font.setTypeface(new drawing.Typeface()); 4379font.setBaselineSnap(true); 4380console.info("drawing font isBaselineSnap: " + font.isBaselineSnap()); 4381``` 4382 4383### setEmbeddedBitmaps<sup>12+</sup> 4384 4385setEmbeddedBitmaps(isEmbeddedBitmaps: boolean): void 4386 4387Sets whether to use bitmaps in this font. 4388 4389**System capability**: SystemCapability.Graphics.Drawing 4390 4391**Parameters** 4392 4393| Name | Type | Mandatory| Description | 4394| -------- | ------ | ---- | ---------------- | 4395| isEmbeddedBitmaps | boolean | Yes | Whether to use bitmaps in the font. The value **true** means to use bitmaps in the font, and **false** means the opposite.| 4396 4397**Error codes** 4398 4399For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4400 4401| ID| Error Message| 4402| ------- | --------------------------------------------| 4403| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4404 4405**Example** 4406 4407```ts 4408import { drawing } from '@kit.ArkGraphics2D'; 4409 4410let font : drawing.Font = new drawing.Font(); 4411font.setTypeface(new drawing.Typeface()); 4412font.setEmbeddedBitmaps(false); 4413console.info("draw isEmbeddedBitmaps: " + font.isEmbeddedBitmaps()); 4414``` 4415 4416### isEmbeddedBitmaps()<sup>12+</sup> 4417 4418isEmbeddedBitmaps(): boolean 4419 4420Checks whether bitmaps are used in this font. 4421 4422**System capability**: SystemCapability.Graphics.Drawing 4423 4424**Return value** 4425 4426| Type | Description | 4427| ------ | ---------------- | 4428| boolean | Result indicating whether the bitmaps are used in the font. The value **true** means that the bitmaps are used, and **false** means the opposite.| 4429 4430**Example** 4431 4432```ts 4433import { drawing } from '@kit.ArkGraphics2D'; 4434 4435let font : drawing.Font = new drawing.Font(); 4436font.setTypeface(new drawing.Typeface()); 4437font.setEmbeddedBitmaps(true); 4438console.info("draw isEmbeddedBitmaps: " + font.isEmbeddedBitmaps()); 4439``` 4440 4441### setForceAutoHinting<sup>12+</sup> 4442 4443setForceAutoHinting(isForceAutoHinting: boolean): void 4444 4445Sets whether to forcibly use auto hinting, that is, whether to always hint glyphs. 4446 4447**System capability**: SystemCapability.Graphics.Drawing 4448 4449**Parameters** 4450 4451| Name | Type | Mandatory| Description | 4452| -------- | ------ | ---- | ---------------- | 4453| isForceAutoHinting | boolean | Yes | Whether to forcibly use auto hinting. The value **true** means to forcibly use auto hinting, and **false** means the opposite.| 4454 4455**Error codes** 4456 4457For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4458 4459| ID| Error Message| 4460| ------- | --------------------------------------------| 4461| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4462 4463**Example** 4464 4465```ts 4466import { drawing } from '@kit.ArkGraphics2D'; 4467 4468let font : drawing.Font = new drawing.Font(); 4469font.setTypeface(new drawing.Typeface()); 4470font.setForceAutoHinting(false); 4471console.info("drawing isForceAutoHinting: " + font.isForceAutoHinting()); 4472``` 4473 4474### isForceAutoHinting<sup>12+</sup> 4475 4476isForceAutoHinting(): boolean 4477 4478Checks whether auto hinting is forcibly used. 4479 4480**System capability**: SystemCapability.Graphics.Drawing 4481 4482**Return value** 4483 4484| Type | Description | 4485| ------ | ---------------- | 4486| boolean | Result indicating whether auto hinting is forcibly used. The value **true** means that auto hinting is forcibly used, and **false** means the opposite.| 4487 4488**Example** 4489 4490```ts 4491import { drawing } from '@kit.ArkGraphics2D'; 4492 4493let font : drawing.Font = new drawing.Font(); 4494font.setTypeface(new drawing.Typeface()); 4495font.setForceAutoHinting(false); 4496console.info("drawing isForceAutoHinting: " + font.isForceAutoHinting()); 4497``` 4498 4499### getWidths<sup>12+</sup> 4500 4501getWidths(glyphs: Array\<number>): Array\<number> 4502 4503Obtains the width of each glyph in an array. 4504 4505**System capability**: SystemCapability.Graphics.Drawing 4506 4507**Parameters** 4508 4509| Name | Type | Mandatory| Description | 4510| -------- | --------------------- | ---- | ------ | 4511| glyphs | Array\<number> | Yes | Glyph array, which can be generated by [textToGlyphs](#texttoglyphs12).| 4512 4513**Return value** 4514 4515| Type | Description | 4516| ------ | ---------------- | 4517| Array\<number> | Array that holds the obtained glyph widths.| 4518 4519**Error codes** 4520 4521For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4522 4523| ID| Error Message| 4524| ------- | --------------------------------------------| 4525| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4526 4527**Example** 4528 4529```ts 4530import { drawing } from '@kit.ArkGraphics2D'; 4531 4532let font: drawing.Font = new drawing.Font(); 4533let text: string = 'hello world'; 4534let glyphs: number[] = font.textToGlyphs(text); 4535let fontWidths: Array<number> = font.getWidths(glyphs); 4536for (let index = 0; index < fontWidths.length; index++) { 4537 console.info("get fontWidths[", index, "]:", fontWidths[index]); 4538} 4539``` 4540 4541### textToGlyphs<sup>12+</sup> 4542 4543textToGlyphs(text: string, glyphCount?: number): Array\<number> 4544 4545Converts text into glyph indexes. 4546 4547**System capability**: SystemCapability.Graphics.Drawing 4548 4549**Parameters** 4550 4551| Name | Type | Mandatory| Description | 4552| -------- | ----------------------------- | ---- | ---------- | 4553| text | string | Yes | Text string.| 4554| glyphCount | number | No | Number of glyphs represented by the text. The value must be the same as the value obtained from [countText](#counttext12). The default value is the number of characters in the text string. The value is an integer.| 4555 4556**Return value** 4557 4558| Type | Description | 4559| ------ | ---------------- | 4560| Array\<number> | Array that holds the glyph indexes.| 4561 4562**Error codes** 4563 4564For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4565 4566| ID| Error Message| 4567| ------- | --------------------------------------------| 4568| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4569 4570**Example** 4571 4572```ts 4573import { drawing } from '@kit.ArkGraphics2D'; 4574 4575let font : drawing.Font = new drawing.Font(); 4576let text : string = 'hello world'; 4577let glyphs : number[] = font.textToGlyphs(text); 4578console.info("drawing text toglyphs OnTestFunction num = " + glyphs.length ); 4579``` 4580 4581## FontMetricsFlags<sup>12+</sup> 4582 4583Enumerates the font measurement flags, which is used to specify whether a field in the font measurement information is valid. 4584 4585**System capability**: SystemCapability.Graphics.Drawing 4586 4587| Name | Value | Description | 4588| ----------------------------- | --------- | ------------------------------ | 4589| UNDERLINE_THICKNESS_VALID | 1 << 0 | The **underlineThickness** field in the [FontMetrics](#fontmetrics) struct is valid. | 4590| UNDERLINE_POSITION_VALID | 1 << 1 | The **underlinePosition** field in the [FontMetrics](#fontmetrics) struct is valid. | 4591| STRIKETHROUGH_THICKNESS_VALID | 1 << 2 | The **strikethroughThickness** field in the [FontMetrics](#fontmetrics) struct is valid.| 4592| STRIKETHROUGH_POSITION_VALID | 1 << 3 | The **strikethroughPosition** field in the [FontMetrics](#fontmetrics) struct is valid. | 4593| BOUNDS_INVALID | 1 << 4 | The boundary metrics (such as **top**, **bottom**, **xMin**, and **xMax**) in the [FontMetrics](#fontmetrics) struct are invalid. | 4594 4595## FontMetrics 4596 4597Describes the attributes that describe the font size and layout. A typeface has similar font metrics. 4598 4599**System capability**: SystemCapability.Graphics.Drawing 4600 4601| Name | Type | Read Only| Optional| Description | 4602| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | 4603| flags<sup>12+</sup> | [FontMetricsFlags](#fontmetricsflags12) | Yes | Yes | Font measurement flags that are valid. | 4604| top | number | Yes | No | Maximum distance from the baseline to the highest coordinate of the text. The value is a floating point number. | 4605| ascent | number | Yes | No | Distance from the baseline to the highest coordinate of the text. The value is a floating point number. | 4606| descent | number | Yes | No | Distance from the baseline to the lowest coordinate of the text. The value is a floating point number. | 4607| bottom | number | Yes | No | Maximum distance from the baseline to the lowest coordinate of the text. The value is a floating point number. | 4608| leading | number | Yes | No | Interline spacing, that is, the distance from the descent of one line of text to the ascent of the next line. The value is a floating point number.| 4609| avgCharWidth<sup>12+</sup> | number | Yes | Yes | Average character width. | 4610| maxCharWidth<sup>12+</sup> | number | Yes | Yes | Maximum character width. | 4611| xMin<sup>12+</sup> | number | Yes | Yes | Horizontal distance from the leftmost edge of any glyph bounding box to the origin. This value is usually less than 0, indicating the minimum horizontal coordinate across all glyph bounding boxes. | 4612| xMax<sup>12+</sup> | number | Yes | Yes | Horizontal distance from the rightmost edge of any glyph bounding box to the origin. The value is a positive number, indicating the maximum horizontal coordinate across all glyph bounding boxes. | 4613| xHeight<sup>12+</sup> | number | Yes | Yes | Height of the lowercase letter x. The value is usually a negative value. | 4614| capHeight<sup>12+</sup> | number | Yes | Yes | Height of a capital letter. The value is usually a negative value. | 4615| underlineThickness<sup>12+</sup> | number | Yes | Yes | Thickness of the underline. | 4616| underlinePosition<sup>12+</sup> | number | Yes | Yes | Vertical distance from the baseline to the top of the underline. The value is usually a positive number. | 4617| strikethroughThickness<sup>12+</sup> | number | Yes | Yes | Thickness of the strikethrough. | 4618| strikethroughPosition<sup>12+</sup> | number | Yes | Yes | Vertical distance from the baseline to the bottom of the strikethrough. The value is usually a negative value. | 4619 4620## ColorFilter 4621 4622Defines a color filter. 4623 4624### createBlendModeColorFilter 4625 4626createBlendModeColorFilter(color: common2D.Color, mode: BlendMode) : ColorFilter 4627 4628Creates a **ColorFilter** object with a given color and blend mode. 4629 4630**System capability**: SystemCapability.Graphics.Drawing 4631 4632**Parameters** 4633 4634| Name| Type | Mandatory| Description | 4635| ------ | ---------------------------------------------------- | ---- | ---------------- | 4636| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255.| 4637| mode | [BlendMode](#blendmode) | Yes | Blend mode.| 4638 4639**Return value** 4640 4641| Type | Description | 4642| --------------------------- | ------------------ | 4643| [ColorFilter](#colorfilter) | **ColorFilter** object created.| 4644 4645**Error codes** 4646 4647For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4648 4649| ID| Error Message| 4650| ------- | --------------------------------------------| 4651| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 4652 4653**Example** 4654 4655```ts 4656import { common2D, drawing } from '@kit.ArkGraphics2D'; 4657const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 4658let colorFilter = drawing.ColorFilter.createBlendModeColorFilter(color, drawing.BlendMode.SRC); 4659``` 4660 4661### createComposeColorFilter 4662 4663createComposeColorFilter(outer: ColorFilter, inner: ColorFilter) : ColorFilter 4664 4665Creates a **ColorFilter** object by combining another two color filters. 4666 4667**System capability**: SystemCapability.Graphics.Drawing 4668 4669**Parameters** 4670 4671| Name| Type | Mandatory| Description | 4672| ------ | --------------------------- | ---- | -------------------------------- | 4673| outer | [ColorFilter](#colorfilter) | Yes | Color filter that takes effect later in the new filter.| 4674| inner | [ColorFilter](#colorfilter) | Yes | Color filter that takes effect first in the new filter.| 4675 4676**Return value** 4677 4678| Type | Description | 4679| --------------------------- | ------------------ | 4680| [ColorFilter](#colorfilter) | **ColorFilter** object created.| 4681 4682**Error codes** 4683 4684For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4685 4686| ID| Error Message| 4687| ------- | --------------------------------------------| 4688| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4689 4690**Example** 4691 4692```ts 4693import { common2D, drawing } from '@kit.ArkGraphics2D'; 4694const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 4695let colorFilter1 = drawing.ColorFilter.createBlendModeColorFilter(color, drawing.BlendMode.SRC); 4696let colorFilter2 = drawing.ColorFilter.createBlendModeColorFilter(color, drawing.BlendMode.DST); 4697let colorFilter = drawing.ColorFilter.createComposeColorFilter(colorFilter1, colorFilter2); 4698``` 4699 4700### createLinearToSRGBGamma 4701 4702createLinearToSRGBGamma() : ColorFilter 4703 4704Creates a **ColorFilter** object that applies the sRGB gamma curve to the RGB channels. 4705 4706**System capability**: SystemCapability.Graphics.Drawing 4707 4708**Return value** 4709 4710| Type | Description | 4711| --------------------------- | ------------------ | 4712| [ColorFilter](#colorfilter) | **ColorFilter** object created.| 4713 4714**Example** 4715 4716```ts 4717import { drawing } from '@kit.ArkGraphics2D'; 4718let colorFilter = drawing.ColorFilter.createLinearToSRGBGamma(); 4719``` 4720 4721### createSRGBGammaToLinear 4722 4723createSRGBGammaToLinear() : ColorFilter 4724 4725Creates a **ColorFilter** object that applies the RGB channels to the sRGB gamma curve. 4726 4727**System capability**: SystemCapability.Graphics.Drawing 4728 4729**Return value** 4730 4731| Type | Description | 4732| --------------------------- | ------------------ | 4733| [ColorFilter](#colorfilter) | **ColorFilter** object created.| 4734 4735**Example** 4736 4737```ts 4738import { drawing } from '@kit.ArkGraphics2D'; 4739let colorFilter = drawing.ColorFilter.createSRGBGammaToLinear(); 4740``` 4741 4742### createLumaColorFilter 4743 4744createLumaColorFilter() : ColorFilter 4745 4746Creates a **ColorFilter** object that multiplies the luma into the alpha channel. 4747 4748**System capability**: SystemCapability.Graphics.Drawing 4749 4750**Return value** 4751 4752| Type | Description | 4753| --------------------------- | ------------------ | 4754| [ColorFilter](#colorfilter) | **ColorFilter** object created.| 4755 4756**Example** 4757 4758```ts 4759import { drawing } from '@kit.ArkGraphics2D'; 4760let colorFilter = drawing.ColorFilter.createLumaColorFilter(); 4761``` 4762 4763### createMatrixColorFilter<sup>12+</sup> 4764 4765static createMatrixColorFilter(matrix: Array\<number>): ColorFilter 4766 4767Creates a color filter object with a 4*5 color matrix. 4768 4769**System capability**: SystemCapability.Graphics.Drawing 4770 4771**Parameters** 4772 4773| Name | Type | Mandatory| Description | 4774| -------- | -------------------------------------------- | ---- | ------------------------------- | 4775| matrix | Array\<number> | Yes | An array of 20 numbers, indicating the 4*5 matrix. | 4776 4777**Return value** 4778 4779| Type | Description | 4780| --------------------------- | ------------------ | 4781| [ColorFilter](#colorfilter) | Color filter created.| 4782 4783**Error codes** 4784 4785For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4786 4787| ID| Error Message| 4788| ------- | --------------------------------------------| 4789| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 4790 4791**Example** 4792 4793```ts 4794import { drawing } from '@kit.ArkGraphics2D'; 4795let matrix: Array<number> = [ 4796 1, 0, 0, 0, 0, 4797 0, 1, 0, 0, 0, 4798 0, 0, 100, 0, 0, 4799 0, 0, 0, 1, 0 4800]; 4801let colorFilter = drawing.ColorFilter.createMatrixColorFilter(matrix); 4802``` 4803 4804## JoinStyle<sup>12+</sup> 4805 4806Enumerates the join styles of a pen. The join style defines the shape of the joints of a polyline segment drawn by the pen. 4807 4808**System capability**: SystemCapability.Graphics.Drawing 4809 4810| Name | Value | Description | Diagram | 4811| ----------- | ---- | ----------------------------------------------------------- | -------- | 4812| MITER_JOIN | 0 | Mitered corner. If the angle of a polyline is small, its miter length may be inappropriate. In this case, you need to use the miter limit to limit the miter length.|  | 4813| ROUND_JOIN | 1 | Round corner.|  | 4814| BEVEL_JOIN | 2 | Beveled corner.|  | 4815 4816## CapStyle<sup>12+</sup> 4817 4818Enumerates the cap styles of a pen. The cap style defines the style of both ends of a line segment drawn by the pen. 4819 4820**System capability**: SystemCapability.Graphics.Drawing 4821 4822| Name | Value | Description | Diagram | 4823| ---------- | ---- | ----------------------------------------------------------- | -------- | 4824| FLAT_CAP | 0 | There is no cap style. Both ends of the line segment are cut off square.|  | 4825| SQUARE_CAP | 1 | Square cap style. Both ends have a square, the height of which is half of the width of the line segment, with the same width.|  | 4826| ROUND_CAP | 2 | Round cap style. Both ends have a semicircle centered, the diameter of which is the same as the width of the line segment.|  | 4827 4828## BlurType<sup>12+</sup> 4829 4830Enumerates the blur types of a mask filter. 4831 4832**System capability**: SystemCapability.Graphics.Drawing 4833 4834| Name | Value| Description | Diagram | 4835| ------ | - | ------------------ | -------- | 4836| NORMAL | 0 | Blurs both inside and outside the original border. |  | 4837| SOLID | 1 | Draws solid inside the border, and blurs outside.|  | 4838| OUTER | 2 | Draws nothing inside the border, and blurs outside.|  | 4839| INNER | 3 | Blurs inside the border, and draws nothing outside.|  | 4840 4841## SamplingOptions<sup>12+</sup> 4842 4843Implements sampling options. 4844 4845### constructor<sup>12+</sup> 4846 4847constructor() 4848 4849Creates a **SamplingOptions** object. 4850 4851**System capability**: SystemCapability.Graphics.Drawing 4852 4853**Example** 4854 4855```ts 4856import { RenderNode } from '@kit.ArkUI'; 4857import { common2D, drawing } from '@kit.ArkGraphics2D'; 4858class DrawingRenderNode extends RenderNode { 4859 draw(context : DrawContext) { 4860 const canvas = context.canvas; 4861 const pen = new drawing.Pen(); 4862 let samplingOptions = new drawing.SamplingOptions(); 4863 } 4864} 4865``` 4866 4867### constructor<sup>12+</sup> 4868 4869constructor(filterMode: FilterMode) 4870 4871Creates a **SamplingOptions** object. 4872 4873**System capability**: SystemCapability.Graphics.Drawing 4874 4875**Parameters** 4876 4877| Name | Type | Mandatory| Description | 4878| ---------- | --------------------- | ---- | ----------------------------------- | 4879| filterMode | [FilterMode](#filtermode12) | Yes | Filter mode. | 4880 4881**Error codes** 4882 4883For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4884 4885| ID| Error Message| 4886| ------- | --------------------------------------------| 4887| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 4888 4889**Example** 4890 4891```ts 4892import { RenderNode } from '@kit.ArkUI'; 4893import { common2D, drawing } from '@kit.ArkGraphics2D'; 4894class DrawingRenderNode extends RenderNode { 4895 draw(context : DrawContext) { 4896 const canvas = context.canvas; 4897 let samplingOptions = new drawing.SamplingOptions(drawing.FilterMode.FILTER_MODE_NEAREST); 4898 } 4899} 4900``` 4901 4902## Lattice<sup>12+</sup> 4903 4904Implements a lattice object, which is used to divide an image by lattice. 4905 4906### createImageLattice<sup>12+</sup> 4907 4908static createImageLattice(xDivs: Array\<number>, yDivs: Array\<number>, fXCount: number, fYCount: number, fBounds?: common2D.Rect | null, fRectTypes?: Array\<RectType> | null, fColors?: Array\<common2D.Color> | null): Lattice 4909 4910Divides the image into lattices. The lattices on both even columns and even rows are fixed, and they are drawn at their original size if the target is large enough. If the target is too small to hold the fixed lattices, all the fixed lattices are scaled down to fit the target, and the lattices that are not on even columns and even rows are scaled to accommodate the remaining space. 4911 4912**System capability**: SystemCapability.Graphics.Drawing 4913 4914**Parameters** 4915 4916| Name | Type | Mandatory| Description | 4917| ------------ | ------------------------------------------------------------------ | ---- | --------------------------------------------------------------------------------- | 4918| xDivs | Array\<number> | Yes | Array of X coordinates used to divide the image. The value is an integer. | 4919| yDivs | Array\<number> | Yes | Array of Y coordinates used to divide the image. The value is an integer. | 4920| fXCount | number | Yes | Size of the array that holds the X coordinates. The value range is [0, 5]. | 4921| fYCount | number | Yes | Size of the array that holds the Y coordinates. The value range is [0, 5]. | 4922| fBounds | [common2D.Rect](js-apis-graphics-common2D.md#rect)\|null | No | Source bounds to draw. The rectangle parameter must be an integer. The default value is the rectangle size of the original image. If the rectangle parameter is a decimal, the decimal part is discarded and converted into an integer.| 4923| fRectTypes | Array\<[RectType](#recttype12)>\|null | No | Array that holds the rectangle types. The default value is null. If this parameter is specified, the array size must be (fXCount + 1) * (fYCount + 1).| 4924| fColors | Array\<[common2D.Color](js-apis-graphics-common2D.md#color)>\|null | No | Array that holds the colors used to fill the lattices. The default value is null. If this parameter is specified, the array size must be (fXCount + 1) * (fYCount + 1).| 4925 4926**Return value** 4927 4928| Type | Description | 4929| ------------------------- | ----------------------------------- | 4930| [Lattice](#lattice12) | **Lattice** object obtained. | 4931 4932**Error codes** 4933 4934For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4935 4936| ID| Error Message| 4937| ------- | --------------------------------------------| 4938| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 4939 4940**Example** 4941 4942```ts 4943import { RenderNode } from '@kit.ArkUI'; 4944import { drawing } from '@kit.ArkGraphics2D'; 4945class DrawingRenderNode extends RenderNode { 4946 draw(context : DrawContext) { 4947 let xDivs : Array<number> = [1, 2, 4]; 4948 let yDivs : Array<number> = [1, 2, 4]; 4949 let lattice = drawing.Lattice.createImageLattice(xDivs, yDivs, 3, 3); // The image is divided into lattices of (3 + 1) x (3 + 1). The blue rectangles in the figure below are fixed lattices. 4950 } 4951} 4952``` 4953 4954 4955## RectType<sup>12+</sup> 4956 4957Enumerates the types of rectangles used to fill the lattices. This enum is used only in [Lattice](#lattice12). 4958 4959**System capability**: SystemCapability.Graphics.Drawing 4960 4961| Name | Value | Description | 4962| ------------ | ---- | --------------------------------------------------------------- | 4963| DEFAULT | 0 | Draws an image into the lattice. | 4964| TRANSPARENT | 1 | Sets the lattice to transparent. | 4965| FIXEDCOLOR | 2 | Draws the colors in the **fColors** array in [Lattice](#lattice12) into the lattice. | 4966 4967## MaskFilter<sup>12+</sup> 4968 4969Implements a mask filter. 4970 4971### createBlurMaskFilter<sup>12+</sup> 4972 4973static createBlurMaskFilter(blurType: BlurType, sigma: number): MaskFilter 4974 4975Creates a mask filter with a blur effect. 4976 4977**System capability**: SystemCapability.Graphics.Drawing 4978 4979**Parameters** 4980 4981| Name | Type | Mandatory| Description | 4982| ---------- | --------------------- | ---- | ----------------------------------- | 4983| blurType | [BlurType](#blurtype12) | Yes | Blur type. | 4984| sigma | number | Yes | Standard deviation of the Gaussian blur to apply. The value must be a floating point number greater than 0.| 4985 4986**Return value** 4987 4988| Type | Description | 4989| ------------------------- | ------------------ | 4990| [MaskFilter](#maskfilter12) | **MaskFilter** object created.| 4991 4992**Error codes** 4993 4994For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4995 4996| ID| Error Message| 4997| ------- | --------------------------------------------| 4998| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 4999 5000**Example** 5001 5002```ts 5003import { RenderNode } from '@kit.ArkUI'; 5004import { common2D, drawing } from '@kit.ArkGraphics2D'; 5005class DrawingRenderNode extends RenderNode { 5006 draw(context : DrawContext) { 5007 const canvas = context.canvas; 5008 let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10); 5009 } 5010} 5011``` 5012 5013## PathEffect<sup>12+</sup> 5014 5015Implements a path effect. 5016 5017### createDashPathEffect<sup>12+</sup> 5018 5019static createDashPathEffect(intervals: Array\<number>, phase: number): PathEffect 5020 5021Creates a **PathEffect** object that converts a path into a dotted line. 5022 5023**System capability**: SystemCapability.Graphics.Drawing 5024 5025**Parameters** 5026 5027| Name | Type | Mandatory | Description | 5028| ---------- | ------------- | ------- | -------------------------------------------------- | 5029| intervals | Array\<number> | Yes | Array of ON and OFF lengths of dotted lines. The number of arrays must be an even number and be greater than or equal to 2.| 5030| phase | number | Yes | Offset used during drawing. The value is a floating point number. | 5031 5032**Return value** 5033 5034| Type | Description | 5035| ------------------------- | --------------------- | 5036| [PathEffect](#patheffect12) | **PathEffect** object created.| 5037 5038**Error codes** 5039 5040For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5041 5042| ID| Error Message| 5043| ------- | --------------------------------------------| 5044| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5045 5046**Example** 5047 5048```ts 5049import { RenderNode } from '@kit.ArkUI'; 5050import { common2D, drawing } from '@kit.ArkGraphics2D'; 5051class DrawingRenderNode extends RenderNode { 5052 draw(context : DrawContext) { 5053 const canvas = context.canvas; 5054 let intervals = [10, 5]; 5055 let effect = drawing.PathEffect.createDashPathEffect(intervals, 5); 5056 } 5057} 5058``` 5059 5060### createCornerPathEffect<sup>12+</sup> 5061 5062static createCornerPathEffect(radius: number): PathEffect 5063 5064Creates a path effect that transforms the sharp angle between line segments into a rounded corner with the specified radius. 5065 5066**System capability**: SystemCapability.Graphics.Drawing 5067 5068**Parameters** 5069 5070| Name | Type | Mandatory | Description | 5071| ---------- | ------------- | ------- | -------------------------------------------------- | 5072| radius | number | Yes | Radius of the rounded corner. The value must be greater than 0. The value is a floating point number. | 5073 5074**Return value** 5075 5076| Type | Description | 5077| ------------------------- | --------------------- | 5078| [PathEffect](#patheffect12) | **PathEffect** object created.| 5079 5080**Error codes** 5081 5082For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5083 5084| ID| Error Message| 5085| ------- | --------------------------------------------| 5086| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5087 5088**Example** 5089 5090```ts 5091import { RenderNode } from '@kit.ArkUI'; 5092import { drawing } from '@kit.ArkGraphics2D'; 5093class DrawingRenderNode extends RenderNode { 5094 draw(context : DrawContext) { 5095 const canvas = context.canvas; 5096 let effect = drawing.PathEffect.createCornerPathEffect(30); 5097 } 5098} 5099``` 5100 5101## ShadowLayer<sup>12+</sup> 5102 5103Implements a shadow layer. 5104 5105### create<sup>12+</sup> 5106 5107static create(blurRadius: number, x: number, y: number, color: common2D.Color): ShadowLayer 5108 5109Creates a **ShadowLayer** object. 5110 5111**System capability**: SystemCapability.Graphics.Drawing 5112 5113**Parameters** 5114 5115| Name | Type | Mandatory| Description | 5116| ---------- | -------- | ---- | ----------------------------------- | 5117| blurRadius | number | Yes | Radius of the shadow layer. The value must be a floating point number greater than 0. | 5118| x | number | Yes | Offset on the X axis. The value is a floating point number. | 5119| y | number | Yes | Offset on the Y axis. The value is a floating point number. | 5120| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255.| 5121 5122**Return value** 5123 5124| Type | Description | 5125| --------------------------- | -------------------- | 5126| [ShadowLayer](#shadowlayer12) | **ShadowLayer** object created.| 5127 5128**Error codes** 5129 5130For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5131 5132| ID| Error Message| 5133| ------- | --------------------------------------------| 5134| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5135 5136**Example** 5137 5138```ts 5139import { RenderNode } from '@kit.ArkUI'; 5140import { common2D, drawing } from '@kit.ArkGraphics2D'; 5141class DrawingRenderNode extends RenderNode { 5142 draw(context : DrawContext) { 5143 const canvas = context.canvas; 5144 let color : common2D.Color = {alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00}; 5145 let shadowLayer = drawing.ShadowLayer.create(3, -3, 3, color); 5146 } 5147} 5148``` 5149 5150## Pen 5151 5152Defines a pen, which is used to describe the style and color to outline a shape. 5153 5154### constructor<sup>12+</sup> 5155 5156constructor() 5157 5158A constructor used to create a **Pen** object. 5159 5160**System capability**: SystemCapability.Graphics.Drawing 5161 5162**Example** 5163 5164```ts 5165import { drawing } from '@kit.ArkGraphics2D'; 5166 5167const pen = new drawing.Pen(); 5168``` 5169 5170### constructor<sup>12+</sup> 5171 5172constructor(pen: Pen) 5173 5174Copies a **Pen** object to create a new one. 5175 5176**System capability**: SystemCapability.Graphics.Drawing 5177 5178**Parameters** 5179 5180| Name| Type | Mandatory| Description | 5181| ------| ----------- | ---- | ---------------- | 5182| pen | [Pen](#pen) | Yes | **Pen** object to copy.| 5183 5184**Error codes** 5185 5186For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5187 5188| ID| Error Message| 5189| ------- | --------------------------------------------| 5190| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5191 5192**Example** 5193 5194```ts 5195import { common2D, drawing } from '@kit.ArkGraphics2D'; 5196 5197const pen = new drawing.Pen(); 5198const penColor: common2D.Color = { alpha: 255, red: 0, green: 255, blue: 0 }; 5199pen.setColor(penColor); 5200pen.setStrokeWidth(10); 5201const newPen = new drawing.Pen(pen); 5202``` 5203 5204### setMiterLimit<sup>12+</sup> 5205 5206setMiterLimit(miter: number): void 5207 5208Sets the maximum ratio allowed between the sharp corner length of a polyline and its line width. When drawing a polyline with the pen, if [JoinStyle](#joinstyle12) is set to **MITER_JOIN** and this maximum ratio is exceeded, the corner will be displayed as beveled instead of mitered. 5209 5210**System capability**: SystemCapability.Graphics.Drawing 5211 5212**Parameters** 5213 5214| Name| Type | Mandatory| Description | 5215| ------ | ------ | ---- | ---------------- | 5216| miter | number | Yes | Maximum ratio of the sharp corner length of the polyline to the line width. A negative number is processed as 4.0 during drawing. Non-negative numbers take effect normally. The value is a floating point number.| 5217 5218**Error codes** 5219 5220For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5221 5222| ID| Error Message| 5223| ------- | --------------------------------------------| 5224| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5225 5226**Example** 5227 5228```ts 5229import { drawing } from '@kit.ArkGraphics2D'; 5230 5231const pen = new drawing.Pen(); 5232pen.setMiterLimit(5); 5233``` 5234 5235### getMiterLimit<sup>12+</sup> 5236 5237getMiterLimit(): number 5238 5239Obtains the maximum ratio allowed between the sharp corner length of a polyline and its line width. 5240 5241**System capability**: SystemCapability.Graphics.Drawing 5242 5243**Return value** 5244 5245| Type | Description | 5246| -------| -------------------- | 5247| number | Maximum ratio obtained.| 5248 5249**Example** 5250 5251```ts 5252import { drawing } from '@kit.ArkGraphics2D'; 5253 5254const pen = new drawing.Pen(); 5255let miter = pen.getMiterLimit(); 5256``` 5257 5258### setImageFilter<sup>12+</sup> 5259 5260setImageFilter(filter: ImageFilter | null): void 5261 5262Sets an image filter for this pen. 5263 5264**System capability**: SystemCapability.Graphics.Drawing 5265 5266**Parameters** 5267 5268| Name| Type | Mandatory| Description | 5269| ------ | ------ | ---- | ----------------------- | 5270| filter | [ImageFilter](#imagefilter12) \| null | Yes | Image filter. If null is passed in, the image filter effect of the pen will be cleared.| 5271 5272**Error codes** 5273 5274For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5275 5276| ID| Error Message| 5277| ------- | --------------------------------------------| 5278| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types. | 5279 5280**Example** 5281 5282```ts 5283import {drawing} from '@kit.ArkGraphics2D'; 5284let colorfilter = drawing.ColorFilter.createSRGBGammaToLinear(); 5285let imgFilter = drawing.ImageFilter.createFromColorFilter(colorfilter); 5286let pen = new drawing.Pen(); 5287pen.setImageFilter(imgFilter); 5288pen.setImageFilter(null); 5289``` 5290 5291### getColorFilter<sup>12+</sup> 5292 5293getColorFilter(): ColorFilter 5294 5295Obtains the color filter of this pen. 5296 5297**System capability**: SystemCapability.Graphics.Drawing 5298 5299**Return value** 5300 5301| Type | Description | 5302| --------------------------- | ------------------ | 5303| [ColorFilter](#colorfilter) | Color filter.| 5304 5305**Example** 5306 5307```ts 5308import {drawing} from '@kit.ArkGraphics2D'; 5309let pen = new drawing.Pen(); 5310let colorfilter = drawing.ColorFilter.createLumaColorFilter(); 5311pen.setColorFilter(colorfilter); 5312let filter = pen.getColorFilter(); 5313``` 5314 5315### setColor 5316 5317setColor(color: common2D.Color) : void 5318 5319Sets a color for this pen. 5320 5321**System capability**: SystemCapability.Graphics.Drawing 5322 5323**Parameters** 5324 5325| Name| Type | Mandatory| Description | 5326| ------ | ---------------------------------------------------- | ---- | ---------------- | 5327| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255.| 5328 5329**Error codes** 5330 5331For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5332 5333| ID| Error Message| 5334| ------- | --------------------------------------------| 5335| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5336 5337**Example** 5338 5339```ts 5340import { common2D, drawing } from '@kit.ArkGraphics2D'; 5341const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 5342const pen = new drawing.Pen(); 5343pen.setColor(color); 5344``` 5345 5346### setColor<sup>12+</sup> 5347 5348setColor(alpha: number, red: number, green: number, blue: number): void 5349 5350Sets a color for this pen. This API provides better performance than [setColor](#setcolor) and is recommended. 5351 5352**System capability**: SystemCapability.Graphics.Drawing 5353 5354**Parameters** 5355 5356| Name| Type | Mandatory| Description | 5357| ------ | ------ | ---- | -------------------------------------------------- | 5358| alpha | number | Yes | Alpha channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.| 5359| red | number | Yes | Red channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 5360| green | number | Yes | Green channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 5361| blue | number | Yes | Blue channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 5362 5363**Error codes** 5364 5365For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5366 5367| ID| Error Message| 5368| ------- | --------------------------------------------| 5369| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5370 5371**Example** 5372 5373```ts 5374import { drawing } from '@kit.ArkGraphics2D'; 5375const pen = new drawing.Pen(); 5376pen.setColor(255, 255, 0, 0); 5377``` 5378 5379### getColor<sup>12+</sup> 5380 5381getColor(): common2D.Color 5382 5383Obtains the color of this pen. 5384 5385**System capability**: SystemCapability.Graphics.Drawing 5386 5387**Return value** 5388 5389| Type | Description | 5390| -------------- | -------------- | 5391| common2D.Color | Color of the pen.| 5392 5393**Example** 5394 5395```ts 5396import { common2D, drawing } from '@kit.ArkGraphics2D'; 5397 5398const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 5399const pen = new drawing.Pen(); 5400pen.setColor(color); 5401let colorGet = pen.getColor(); 5402``` 5403 5404### setStrokeWidth 5405 5406setStrokeWidth(width: number) : void 5407 5408Sets the stroke width for this pen. The value **0** is treated as an unusually thin width. During drawing, the width of 0 is always drawn as 1 pixel wide, regardless of any scaling applied to the canvas. Negative values are also regarded as the value **0** during the drawing process. 5409 5410**System capability**: SystemCapability.Graphics.Drawing 5411 5412**Parameters** 5413 5414| Name| Type | Mandatory| Description | 5415| ------ | ------ | ---- | ---------------- | 5416| width | number | Yes | Stroke width. The value is a floating point number.| 5417 5418**Error codes** 5419 5420For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5421 5422| ID| Error Message| 5423| ------- | --------------------------------------------| 5424| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5425 5426**Example** 5427 5428```ts 5429import { drawing } from '@kit.ArkGraphics2D'; 5430const pen = new drawing.Pen(); 5431pen.setStrokeWidth(5); 5432``` 5433 5434### getWidth<sup>12+</sup> 5435 5436getWidth(): number 5437 5438Obtains the stroke width of this pen. The width describes the thickness of the outline of a shape. 5439 5440**System capability**: SystemCapability.Graphics.Drawing 5441 5442**Return value** 5443 5444| Type | Description | 5445| ------ | -------------- | 5446| number | Stroke width of the pen.| 5447 5448**Example** 5449 5450```ts 5451import { drawing } from '@kit.ArkGraphics2D'; 5452 5453const pen = new drawing.Pen(); 5454let width = pen.getWidth(); 5455``` 5456 5457### setAntiAlias 5458 5459setAntiAlias(aa: boolean) : void 5460 5461Enables anti-aliasing for this pen. Anti-aliasing makes the edges of the content smoother. 5462 5463**System capability**: SystemCapability.Graphics.Drawing 5464 5465**Parameters** 5466 5467| Name| Type | Mandatory| Description | 5468| ------ | ------- | ---- | ------------------------------------------------- | 5469| aa | boolean | Yes | Whether to enable anti-aliasing. The value **true** means to enable anti-aliasing, and **false** means the opposite.| 5470 5471**Error codes** 5472 5473For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5474 5475| ID| Error Message| 5476| ------- | --------------------------------------------| 5477| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5478 5479**Example** 5480 5481```ts 5482import { drawing } from '@kit.ArkGraphics2D'; 5483const pen = new drawing.Pen(); 5484pen.setAntiAlias(true); 5485``` 5486 5487### isAntiAlias<sup>12+</sup> 5488 5489isAntiAlias(): boolean 5490 5491Checks whether anti-aliasing is enabled for this pen. 5492 5493**System capability**: SystemCapability.Graphics.Drawing 5494 5495**Return value** 5496 5497| Type | Description | 5498| ------- | ------------------------- | 5499| boolean | Result indicating whether anti-aliasing is enabled. The value **true** means that anti-aliasing is enabled, and **false** means the opposite.| 5500 5501**Example** 5502 5503```ts 5504import { drawing } from '@kit.ArkGraphics2D'; 5505 5506const pen = new drawing.Pen(); 5507let isAntiAlias = pen.isAntiAlias(); 5508``` 5509 5510### setAlpha 5511 5512setAlpha(alpha: number) : void 5513 5514Sets an alpha value for this pen. 5515 5516**System capability**: SystemCapability.Graphics.Drawing 5517 5518**Parameters** 5519 5520| Name| Type | Mandatory| Description | 5521| ------ | ------ | ---- | ---------------------------------------- | 5522| alpha | number | Yes | Alpha value. The value is an integer in the range [0, 255]. If a floating point number is passed in, the value is rounded down.| 5523 5524**Error codes** 5525 5526For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5527 5528| ID| Error Message| 5529| ------- | --------------------------------------------| 5530| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5531 5532**Example** 5533 5534```ts 5535import { drawing } from '@kit.ArkGraphics2D'; 5536const pen = new drawing.Pen(); 5537pen.setAlpha(128); 5538``` 5539 5540### getAlpha<sup>12+</sup> 5541 5542getAlpha(): number 5543 5544Obtains the alpha value of this pen. 5545 5546**System capability**: SystemCapability.Graphics.Drawing 5547 5548**Return value** 5549 5550| Type | Description | 5551| ------ | ---------------- | 5552| number | Alpha value of the pen. The return value is an integer ranging from 0 to 255.| 5553 5554**Example** 5555 5556```ts 5557import { drawing } from '@kit.ArkGraphics2D'; 5558 5559const pen = new drawing.Pen(); 5560let alpha = pen.getAlpha(); 5561``` 5562 5563### setColorFilter 5564 5565setColorFilter(filter: ColorFilter) : void 5566 5567Sets a color filter for this pen. 5568 5569**System capability**: SystemCapability.Graphics.Drawing 5570 5571**Parameters** 5572 5573| Name| Type | Mandatory| Description | 5574| ------ | --------------------------- | ---- | ------------ | 5575| filter | [ColorFilter](#colorfilter) | Yes | Color filter. If null is passed in, the color filter is cleared.| 5576 5577**Error codes** 5578 5579For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5580 5581| ID| Error Message| 5582| ------- | --------------------------------------------| 5583| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5584 5585**Example** 5586 5587```ts 5588import { drawing } from '@kit.ArkGraphics2D'; 5589const pen = new drawing.Pen(); 5590let colorFilter = drawing.ColorFilter.createLinearToSRGBGamma(); 5591pen.setColorFilter(colorFilter); 5592``` 5593 5594### setMaskFilter<sup>12+</sup> 5595 5596setMaskFilter(filter: MaskFilter): void 5597 5598Adds a mask filter for this pen. 5599 5600**System capability**: SystemCapability.Graphics.Drawing 5601 5602**Parameters** 5603 5604| Name| Type | Mandatory| Description | 5605| ------ | ------------------------- | ---- | --------- | 5606| filter | [MaskFilter](#maskfilter12) | Yes | Mask filter. If null is passed in, the mask filter is cleared.| 5607 5608**Error codes** 5609 5610For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5611 5612| ID| Error Message| 5613| ------- | --------------------------------------------| 5614| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5615 5616**Example** 5617 5618```ts 5619import { RenderNode } from '@kit.ArkUI'; 5620import { common2D, drawing } from '@kit.ArkGraphics2D'; 5621class DrawingRenderNode extends RenderNode { 5622 draw(context : DrawContext) { 5623 const canvas = context.canvas; 5624 const pen = new drawing.Pen(); 5625 pen.setStrokeWidth(5); 5626 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5627 let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10); 5628 pen.setMaskFilter(maskFilter); 5629 } 5630} 5631``` 5632 5633### setPathEffect<sup>12+</sup> 5634 5635setPathEffect(effect: PathEffect): void 5636 5637Sets the path effect for this pen. 5638 5639**System capability**: SystemCapability.Graphics.Drawing 5640 5641**Parameters** 5642 5643| Name | Type | Mandatory| Description | 5644| ------- | ------------------------- | ---- | ------------ | 5645| effect | [PathEffect](#patheffect12) | Yes | Path effect. If null is passed in, the path filter is cleared.| 5646 5647**Error codes** 5648 5649For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5650 5651| ID| Error Message| 5652| ------- | --------------------------------------------| 5653| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5654 5655**Example** 5656 5657```ts 5658import { RenderNode } from '@kit.ArkUI'; 5659import { common2D, drawing } from '@kit.ArkGraphics2D'; 5660class DrawingRenderNode extends RenderNode { 5661 draw(context : DrawContext) { 5662 const canvas = context.canvas; 5663 const pen = new drawing.Pen(); 5664 pen.setStrokeWidth(5); 5665 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5666 let pathEffect = drawing.PathEffect.createDashPathEffect([30, 10], 0); 5667 pen.setPathEffect(pathEffect); 5668 } 5669} 5670``` 5671 5672### setShaderEffect<sup>12+</sup> 5673 5674setShaderEffect(shaderEffect: ShaderEffect): void 5675 5676Sets the shader effect for this pen. 5677 5678**System capability**: SystemCapability.Graphics.Drawing 5679 5680**Parameters** 5681 5682| Name | Type | Mandatory| Description | 5683| ------- | ------------------------- | ---- | ------------ | 5684| shaderEffect | [ShaderEffect](#shadereffect12) | Yes | **ShaderEffect** object. If null is passed in, the shader effect will be cleared.| 5685 5686**Error codes** 5687 5688For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5689 5690| ID| Error Message| 5691| ------- | --------------------------------------------| 5692| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5693 5694**Example** 5695 5696```ts 5697import { drawing } from '@kit.ArkGraphics2D'; 5698 5699const pen = new drawing.Pen(); 5700let shaderEffect = drawing.ShaderEffect.createLinearGradient({x: 100, y: 100}, {x: 300, y: 300}, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 5701pen.setShaderEffect(shaderEffect); 5702``` 5703 5704### setShadowLayer<sup>12+</sup> 5705 5706setShadowLayer(shadowLayer: ShadowLayer): void 5707 5708Sets a shadow layer for this pen. The shadow layer effect takes effect only when text is drawn. 5709 5710**System capability**: SystemCapability.Graphics.Drawing 5711 5712**Parameters** 5713 5714| Name | Type | Mandatory| Description | 5715| ------- | ------------------------- | ---- | --------- | 5716| shadowLayer | [ShadowLayer](#shadowlayer12) | Yes | Shadow layer. If null is passed in, the shadow layer is cleared.| 5717 5718**Error codes** 5719 5720For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5721 5722| ID| Error Message| 5723| ------- | --------------------------------------------| 5724| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5725 5726**Example** 5727 5728```ts 5729import { RenderNode } from '@kit.ArkUI'; 5730import { common2D, drawing } from '@kit.ArkGraphics2D'; 5731class DrawingRenderNode extends RenderNode { 5732 draw(context : DrawContext) { 5733 const canvas = context.canvas; 5734 let font = new drawing.Font(); 5735 font.setSize(60); 5736 let textBlob = drawing.TextBlob.makeFromString("hello", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 5737 let pen = new drawing.Pen(); 5738 pen.setStrokeWidth(2.0); 5739 let pen_color : common2D.Color = {alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00}; 5740 pen.setColor(pen_color); 5741 canvas.attachPen(pen); 5742 canvas.drawTextBlob(textBlob, 100, 100); 5743 canvas.detachPen(); 5744 let color : common2D.Color = {alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00}; 5745 let shadowLayer = drawing.ShadowLayer.create(3, -3, 3, color); 5746 pen.setShadowLayer(shadowLayer); 5747 canvas.attachPen(pen); 5748 canvas.drawTextBlob(textBlob, 100, 200); 5749 canvas.detachPen(); 5750 } 5751} 5752``` 5753 5754### setBlendMode 5755 5756setBlendMode(mode: BlendMode) : void 5757 5758Sets a blend mode for this pen. 5759 5760**System capability**: SystemCapability.Graphics.Drawing 5761 5762**Parameters** 5763 5764| Name| Type | Mandatory| Description | 5765| ------ | ----------------------- | ---- | ---------------- | 5766| mode | [BlendMode](#blendmode) | Yes | Blend mode.| 5767 5768**Error codes** 5769 5770For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5771 5772| ID| Error Message| 5773| ------- | --------------------------------------------| 5774| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5775 5776**Example** 5777 5778```ts 5779import { drawing } from '@kit.ArkGraphics2D'; 5780const pen = new drawing.Pen(); 5781pen.setBlendMode(drawing.BlendMode.SRC); 5782``` 5783 5784### setJoinStyle<sup>12+</sup> 5785 5786setJoinStyle(style: JoinStyle): void 5787 5788Sets the join style for this pen. 5789 5790**System capability**: SystemCapability.Graphics.Drawing 5791 5792**Parameters** 5793 5794| Name| Type | Mandatory| Description | 5795| ------ | ----------------------- | ---- | --------------- | 5796| style | [JoinStyle](#joinstyle12) | Yes | Join style. | 5797 5798**Error codes** 5799 5800For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5801 5802| ID| Error Message| 5803| ------- | --------------------------------------------| 5804| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5805 5806**Example** 5807 5808```ts 5809import { RenderNode } from '@kit.ArkUI'; 5810import { common2D, drawing } from '@kit.ArkGraphics2D'; 5811class DrawingRenderNode extends RenderNode { 5812 draw(context : DrawContext) { 5813 const canvas = context.canvas; 5814 const pen = new drawing.Pen(); 5815 pen.setStrokeWidth(5); 5816 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5817 pen.setJoinStyle(drawing.JoinStyle.ROUND_JOIN); 5818 } 5819} 5820``` 5821 5822### getJoinStyle<sup>12+</sup> 5823 5824getJoinStyle(): JoinStyle 5825 5826Obtains the join style of this pen. 5827 5828**System capability**: SystemCapability.Graphics.Drawing 5829 5830**Return value** 5831 5832| Type | Description | 5833| ------------- | ---------------------- | 5834| JoinStyle | Join style. | 5835 5836**Example** 5837 5838```ts 5839import { RenderNode } from '@kit.ArkUI'; 5840import { common2D, drawing } from '@kit.ArkGraphics2D'; 5841class DrawingRenderNode extends RenderNode { 5842 draw(context : DrawContext) { 5843 const canvas = context.canvas; 5844 const pen = new drawing.Pen(); 5845 pen.setStrokeWidth(5); 5846 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5847 pen.setJoinStyle(drawing.JoinStyle.ROUND_JOIN); 5848 let joinStyle = pen.getJoinStyle(); 5849 } 5850} 5851``` 5852 5853### setCapStyle<sup>12+</sup> 5854 5855setCapStyle(style: CapStyle): void 5856 5857Sets the cap style for this pen. 5858 5859**System capability**: SystemCapability.Graphics.Drawing 5860 5861**Parameters** 5862 5863| Name| Type | Mandatory| Description | 5864| ------ | ----------------------- | ---- | --------------------- | 5865| style | [CapStyle](#capstyle12) | Yes | A variable that describes the cap style. | 5866 5867**Error codes** 5868 5869For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5870 5871| ID| Error Message| 5872| ------- | --------------------------------------------| 5873| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 5874 5875**Example** 5876 5877```ts 5878import { RenderNode } from '@kit.ArkUI'; 5879import { common2D, drawing } from '@kit.ArkGraphics2D'; 5880class DrawingRenderNode extends RenderNode { 5881 draw(context : DrawContext) { 5882 const canvas = context.canvas; 5883 const pen = new drawing.Pen(); 5884 pen.setStrokeWidth(5); 5885 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5886 pen.setCapStyle(drawing.CapStyle.SQUARE_CAP); 5887 } 5888} 5889``` 5890 5891### getCapStyle<sup>12+</sup> 5892 5893getCapStyle(): CapStyle 5894 5895Obtains the cap style of this pen. 5896 5897**System capability**: SystemCapability.Graphics.Drawing 5898 5899**Return value** 5900 5901| Type | Description | 5902| ------------ | ------------------ | 5903| CapStyle | Cap style.| 5904 5905**Example** 5906 5907```ts 5908import { RenderNode } from '@kit.ArkUI'; 5909import { common2D, drawing } from '@kit.ArkGraphics2D'; 5910class DrawingRenderNode extends RenderNode { 5911 draw(context : DrawContext) { 5912 const canvas = context.canvas; 5913 const pen = new drawing.Pen(); 5914 pen.setStrokeWidth(5); 5915 pen.setColor({alpha: 255, red: 255, green: 0, blue: 0}); 5916 pen.setCapStyle(drawing.CapStyle.SQUARE_CAP); 5917 let capStyle = pen.getCapStyle(); 5918 } 5919} 5920``` 5921 5922### setDither 5923 5924setDither(dither: boolean) : void 5925 5926Enables dithering for this pen. Dithering make the drawn color more realistic. 5927 5928**System capability**: SystemCapability.Graphics.Drawing 5929 5930**Parameters** 5931 5932| Name| Type | Mandatory| Description | 5933| ------ | ------- | ---- | --------------------------------------------------------- | 5934| dither | boolean | Yes | Whether to enable dithering. The value **true** means to enable dithering, and **false** means the opposite.| 5935 5936**Error codes** 5937 5938For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5939 5940| ID| Error Message| 5941| ------- | --------------------------------------------| 5942| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5943 5944**Example** 5945 5946```ts 5947import { drawing } from '@kit.ArkGraphics2D'; 5948const pen = new drawing.Pen(); 5949pen.setDither(true); 5950``` 5951 5952### getFillPath<sup>12+</sup> 5953 5954getFillPath(src: Path, dst: Path): boolean 5955 5956Obtains the source path outline drawn using this pen and represents it using a destination path. 5957 5958**System capability**: SystemCapability.Graphics.Drawing 5959 5960**Parameters** 5961 5962| Name | Type | Mandatory| Description | 5963| -------- | -------------------------------------------- | ---- | ------------------------------- | 5964| src | [Path](#path) | Yes | Source path. | 5965| dst | [Path](#path) | Yes | Destination path.| 5966 5967**Return value** 5968 5969| Type | Description | 5970| --------------------- | -------------- | 5971| boolean | Result indicating whether the source path outline is obtained. The value **true** means that the source path outline is obtained, and **false** means the opposite.| 5972 5973**Error codes** 5974 5975For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5976 5977| ID| Error Message| 5978| ------- | --------------------------------------------| 5979| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 5980 5981**Example** 5982 5983```ts 5984import { drawing } from '@kit.ArkGraphics2D'; 5985let pen = new drawing.Pen(); 5986let pathSrc: drawing.Path = new drawing.Path(); 5987let pathDst: drawing.Path = new drawing.Path(); 5988pathSrc.moveTo(0, 0); 5989pathSrc.lineTo(700, 700); 5990let value = pen.getFillPath(pathSrc, pathDst); 5991``` 5992 5993### reset<sup>12+</sup> 5994 5995reset(): void 5996 5997Resets this pen to the initial state. 5998 5999**System capability**: SystemCapability.Graphics.Drawing 6000 6001**Example** 6002 6003```ts 6004import { drawing } from '@kit.ArkGraphics2D'; 6005 6006const pen = new drawing.Pen(); 6007pen.reset(); 6008``` 6009 6010## Brush 6011 6012Defines a brush, which is used to describe the style and color to fill in a shape. 6013 6014### constructor<sup>12+</sup> 6015 6016constructor() 6017 6018A constructor used to create a **Brush** object. 6019 6020**System capability**: SystemCapability.Graphics.Drawing 6021 6022**Example** 6023 6024```ts 6025import { drawing } from '@kit.ArkGraphics2D'; 6026 6027const brush = new drawing.Brush(); 6028``` 6029 6030### constructor<sup>12+</sup> 6031 6032constructor(brush: Brush) 6033 6034Copies a **Brush** object to create a new one. 6035 6036**System capability**: SystemCapability.Graphics.Drawing 6037 6038**Parameters** 6039 6040| Name| Type | Mandatory| Description | 6041| ------| ----------- | ---- | ---------------- | 6042| brush | [Brush](#brush) | Yes | **Brush** object to copy.| 6043 6044**Error codes** 6045 6046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6047 6048| ID| Error Message| 6049| ------- | --------------------------------------------| 6050| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6051 6052**Example** 6053 6054```ts 6055import { common2D, drawing } from '@kit.ArkGraphics2D'; 6056 6057const brush = new drawing.Brush(); 6058const brushColor: common2D.Color = { alpha: 255, red: 0, green: 255, blue: 0 }; 6059brush.setColor(brushColor); 6060const newBrush = new drawing.Brush(brush); 6061``` 6062 6063### setColor 6064 6065setColor(color: common2D.Color) : void 6066 6067Sets a color for this brush. 6068 6069**System capability**: SystemCapability.Graphics.Drawing 6070 6071**Parameters** 6072 6073| Name| Type | Mandatory| Description | 6074| ------ | ---------------------------------------------------- | ---- | ---------------- | 6075| color | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes | Color in ARGB format. Each color channel is an integer ranging from 0 to 255.| 6076 6077**Error codes** 6078 6079For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6080 6081| ID| Error Message| 6082| ------- | --------------------------------------------| 6083| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 6084 6085**Example** 6086 6087```ts 6088import { common2D, drawing } from '@kit.ArkGraphics2D'; 6089const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 6090const brush = new drawing.Brush(); 6091brush.setColor(color); 6092``` 6093 6094### setColor<sup>12+</sup> 6095 6096setColor(alpha: number, red: number, green: number, blue: number): void 6097 6098Sets a color for this brush. This API provides better performance than [setColor](#setcolor-1) and is recommended. 6099 6100**System capability**: SystemCapability.Graphics.Drawing 6101 6102**Parameters** 6103 6104| Name| Type | Mandatory| Description | 6105| ------ | ------ | ---- | -------------------------------------------------- | 6106| alpha | number | Yes | Alpha channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.| 6107| red | number | Yes | Red channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 6108| green | number | Yes | Green channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 6109| blue | number | Yes | Blue channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down. | 6110 6111**Error codes** 6112 6113For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6114 6115| ID| Error Message| 6116| ------- | --------------------------------------------| 6117| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 6118 6119**Example** 6120 6121```ts 6122import { drawing } from '@kit.ArkGraphics2D'; 6123const brush = new drawing.Brush(); 6124brush.setColor(255, 255, 0, 0); 6125``` 6126 6127### getColor<sup>12+</sup> 6128 6129getColor(): common2D.Color 6130 6131Obtains the color of this brush. 6132 6133**System capability**: SystemCapability.Graphics.Drawing 6134 6135**Return value** 6136 6137| Type | Description | 6138| -------------- | -------------- | 6139| common2D.Color | Color of the brush.| 6140 6141**Example** 6142 6143```ts 6144import { common2D, drawing } from '@kit.ArkGraphics2D'; 6145 6146const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 6147const brush = new drawing.Brush(); 6148brush.setColor(color); 6149let colorGet = brush.getColor(); 6150``` 6151 6152### setAntiAlias 6153 6154setAntiAlias(aa: boolean) : void 6155 6156Enables anti-aliasing for this brush. Anti-aliasing makes the edges of the content smoother. 6157 6158**System capability**: SystemCapability.Graphics.Drawing 6159 6160**Parameters** 6161 6162| Name| Type | Mandatory| Description | 6163| ------ | ------- | ---- | ------------------------------------------------- | 6164| aa | boolean | Yes | Whether to enable anti-aliasing. The value **true** means to enable anti-aliasing, and **false** means the opposite.| 6165 6166**Error codes** 6167 6168For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6169 6170| ID| Error Message| 6171| ------- | --------------------------------------------| 6172| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6173 6174**Example** 6175 6176```ts 6177import { drawing } from '@kit.ArkGraphics2D'; 6178const brush = new drawing.Brush(); 6179brush.setAntiAlias(true); 6180``` 6181 6182### isAntiAlias<sup>12+</sup> 6183 6184isAntiAlias(): boolean 6185 6186Checks whether anti-aliasing is enabled for this brush. 6187 6188**System capability**: SystemCapability.Graphics.Drawing 6189 6190**Return value** 6191 6192| Type | Description | 6193| ------- | ------------------------- | 6194| boolean | Result indicating whether anti-aliasing is enabled. The value **true** means that anti-aliasing is enabled, and **false** means the opposite.| 6195 6196**Example** 6197 6198```ts 6199import { drawing } from '@kit.ArkGraphics2D'; 6200 6201const brush = new drawing.Brush(); 6202let isAntiAlias = brush.isAntiAlias(); 6203``` 6204 6205### setAlpha 6206 6207setAlpha(alpha: number) : void 6208 6209Sets an alpha value for this brush. 6210 6211**System capability**: SystemCapability.Graphics.Drawing 6212 6213**Parameters** 6214 6215| Name| Type | Mandatory| Description | 6216| ------ | ------ | ---- | ---------------------------------------- | 6217| alpha | number | Yes | Alpha value. The value is an integer in the range [0, 255]. If a floating point number is passed in, the value is rounded down.| 6218 6219**Error codes** 6220 6221For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6222 6223| ID| Error Message| 6224| ------- | --------------------------------------------| 6225| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 6226 6227**Example** 6228 6229```ts 6230import { drawing } from '@kit.ArkGraphics2D'; 6231const brush = new drawing.Brush(); 6232brush.setAlpha(128); 6233``` 6234 6235### getAlpha<sup>12+</sup> 6236 6237getAlpha(): number 6238 6239Obtains the alpha value of this brush. 6240 6241**System capability**: SystemCapability.Graphics.Drawing 6242 6243**Return value** 6244 6245| Type | Description | 6246| ------ | ---------------- | 6247| number | Alpha value of the brush. The return value is an integer ranging from 0 to 255.| 6248 6249**Example** 6250 6251```ts 6252import { drawing } from '@kit.ArkGraphics2D'; 6253 6254const brush = new drawing.Brush(); 6255let alpha = brush.getAlpha(); 6256``` 6257 6258### setColorFilter 6259 6260setColorFilter(filter: ColorFilter) : void 6261 6262Sets a color filter for this brush. 6263 6264**System capability**: SystemCapability.Graphics.Drawing 6265 6266**Parameters** 6267 6268| Name| Type | Mandatory| Description | 6269| ------ | --------------------------- | ---- | ------------ | 6270| filter | [ColorFilter](#colorfilter) | Yes | Color filter. If null is passed in, the color filter is cleared.| 6271 6272**Error codes** 6273 6274For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6275 6276| ID| Error Message| 6277| ------- | --------------------------------------------| 6278| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6279 6280**Example** 6281 6282```ts 6283import { drawing } from '@kit.ArkGraphics2D'; 6284const brush = new drawing.Brush(); 6285let colorFilter = drawing.ColorFilter.createLinearToSRGBGamma(); 6286brush.setColorFilter(colorFilter); 6287``` 6288 6289### setMaskFilter<sup>12+</sup> 6290 6291setMaskFilter(filter: MaskFilter): void 6292 6293Adds a mask filter for this brush. 6294 6295**System capability**: SystemCapability.Graphics.Drawing 6296 6297**Parameters** 6298 6299| Name| Type | Mandatory| Description | 6300| ------ | ------------------------- | ---- | --------- | 6301| filter | [MaskFilter](#maskfilter12) | Yes | Mask filter. If null is passed in, the mask filter is cleared.| 6302 6303**Error codes** 6304 6305For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6306 6307| ID| Error Message| 6308| ------- | --------------------------------------------| 6309| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6310 6311**Example** 6312 6313```ts 6314import { RenderNode } from '@kit.ArkUI'; 6315import { common2D, drawing } from '@kit.ArkGraphics2D'; 6316class DrawingRenderNode extends RenderNode { 6317 draw(context : DrawContext) { 6318 const canvas = context.canvas; 6319 const brush = new drawing.Brush(); 6320 let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10); 6321 brush.setMaskFilter(maskFilter); 6322 } 6323} 6324``` 6325 6326### setShaderEffect<sup>12+</sup> 6327 6328setShaderEffect(shaderEffect: ShaderEffect): void 6329 6330Sets the shader effect for this brush. 6331 6332**System capability**: SystemCapability.Graphics.Drawing 6333 6334**Parameters** 6335 6336| Name | Type | Mandatory| Description | 6337| ------- | ------------------------- | ---- | ------------ | 6338| shaderEffect | [ShaderEffect](#shadereffect12) | Yes | **ShaderEffect** object. If null is passed in, the shader effect will be cleared.| 6339 6340**Error codes** 6341 6342For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6343 6344| ID| Error Message| 6345| ------- | --------------------------------------------| 6346| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6347 6348**Example** 6349 6350```ts 6351import { drawing } from '@kit.ArkGraphics2D'; 6352 6353const brush = new drawing.Brush(); 6354let shaderEffect = drawing.ShaderEffect.createLinearGradient({x: 100, y: 100}, {x: 300, y: 300}, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 6355brush.setShaderEffect(shaderEffect); 6356``` 6357 6358### setShadowLayer<sup>12+</sup> 6359 6360setShadowLayer(shadowLayer: ShadowLayer): void 6361 6362Sets a shadow layer for this brush. The shadow layer effect takes effect only when text is drawn. 6363 6364**System capability**: SystemCapability.Graphics.Drawing 6365 6366**Parameters** 6367 6368| Name | Type | Mandatory| Description | 6369| ------- | ------------------------- | ---- | --------- | 6370| shadowLayer | [ShadowLayer](#shadowlayer12) | Yes | Shadow layer. If null is passed in, the shadow layer is cleared.| 6371 6372**Error codes** 6373 6374For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6375 6376| ID| Error Message| 6377| ------- | --------------------------------------------| 6378| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6379 6380**Example** 6381 6382```ts 6383import { RenderNode } from '@kit.ArkUI'; 6384import { common2D, drawing } from '@kit.ArkGraphics2D'; 6385class DrawingRenderNode extends RenderNode { 6386 draw(context : DrawContext) { 6387 const canvas = context.canvas; 6388 let font = new drawing.Font(); 6389 font.setSize(60); 6390 6391 let textBlob = drawing.TextBlob.makeFromString("hello", font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 6392 let pen = new drawing.Pen(); 6393 pen.setStrokeWidth(2.0); 6394 6395 let pen_color : common2D.Color = {alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00}; 6396 pen.setColor(pen_color); 6397 canvas.attachPen(pen); 6398 canvas.drawTextBlob(textBlob, 100, 100); 6399 canvas.detachPen(); 6400 6401 let color : common2D.Color = {alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00}; 6402 let shadowLayer = drawing.ShadowLayer.create(3, -3, 3, color); 6403 pen.setShadowLayer(shadowLayer); 6404 canvas.attachPen(pen); 6405 canvas.drawTextBlob(textBlob, 100, 200); 6406 canvas.detachPen(); 6407 6408 let brush = new drawing.Brush(); 6409 let brush_color : common2D.Color = {alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00}; 6410 brush.setColor(brush_color); 6411 canvas.attachBrush(brush); 6412 canvas.drawTextBlob(textBlob, 300, 100); 6413 canvas.detachBrush(); 6414 6415 brush.setShadowLayer(shadowLayer); 6416 canvas.attachBrush(brush); 6417 canvas.drawTextBlob(textBlob, 300, 200); 6418 canvas.detachBrush(); 6419 } 6420} 6421``` 6422 6423### setBlendMode 6424 6425setBlendMode(mode: BlendMode) : void 6426 6427Sets a blend mode for this brush. 6428 6429**System capability**: SystemCapability.Graphics.Drawing 6430 6431**Parameters** 6432 6433| Name| Type | Mandatory| Description | 6434| ------ | ----------------------- | ---- | ---------------- | 6435| mode | [BlendMode](#blendmode) | Yes | Blend mode.| 6436 6437**Error codes** 6438 6439For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6440 6441| ID| Error Message| 6442| ------- | --------------------------------------------| 6443| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 6444 6445**Example** 6446 6447```ts 6448import { drawing } from '@kit.ArkGraphics2D'; 6449const brush = new drawing.Brush(); 6450brush.setBlendMode(drawing.BlendMode.SRC); 6451``` 6452 6453### setImageFilter<sup>12+</sup> 6454 6455setImageFilter(filter: ImageFilter | null): void 6456 6457Sets an image filter for this brush. 6458 6459**System capability**: SystemCapability.Graphics.Drawing 6460 6461**Parameters** 6462 6463| Name| Type | Mandatory| Description | 6464| ------ | ------ | ---- | ----------------------- | 6465| filter | [ImageFilter](#imagefilter12) \| null | Yes | Image filter. If null is passed in, the image filter effect of the brush will be cleared.| 6466 6467**Error codes** 6468 6469For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6470 6471| ID| Error Message| 6472| ------- | --------------------------------------------| 6473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types. | 6474 6475**Example** 6476 6477```ts 6478import {drawing} from '@kit.ArkGraphics2D'; 6479let brush = new drawing.Brush(); 6480let imgFilter = drawing.ImageFilter.createBlurImageFilter(5, 10, drawing.TileMode.DECAL); 6481brush.setImageFilter(imgFilter); 6482brush.setImageFilter(null); 6483``` 6484 6485### getColorFilter<sup>12+</sup> 6486 6487getColorFilter(): ColorFilter 6488 6489Obtains the color filter of this brush. 6490 6491**System capability**: SystemCapability.Graphics.Drawing 6492 6493**Return value** 6494 6495| Type | Description | 6496| --------------------------- | ------------------ | 6497| [ColorFilter](#colorfilter) | Color filter.| 6498 6499**Example** 6500 6501```ts 6502import {drawing} from '@kit.ArkGraphics2D'; 6503let brush = new drawing.Brush(); 6504let setColorFilter = drawing.ColorFilter.createSRGBGammaToLinear(); 6505brush.setColorFilter(setColorFilter); 6506let filter = brush.getColorFilter(); 6507``` 6508 6509### reset<sup>12+</sup> 6510 6511reset(): void 6512 6513Resets this brush to the initial state. 6514 6515**System capability**: SystemCapability.Graphics.Drawing 6516 6517**Example** 6518 6519```ts 6520import { drawing } from '@kit.ArkGraphics2D'; 6521 6522const brush = new drawing.Brush(); 6523brush.reset(); 6524``` 6525 6526## ScaleToFit<sup>12+</sup> 6527 6528Enumerates the modes of scaling a source rectangle into a destination rectangle. 6529 6530**System capability**: SystemCapability.Graphics.Drawing 6531 6532| Name | Value | Description | 6533| ---------------------- | ---- | ------------------------------ | 6534| FILL_SCALE_TO_FIT | 0 | Scales the source rectangle to completely fill the destination rectangle, potentially changing the aspect ratio of the source rectangle. | 6535| START_SCALE_TO_FIT | 1 | Scales the source rectangle, preserving its aspect ratio, to align it to the upper left corner of the destination rectangle.| 6536| CENTER_SCALE_TO_FIT | 2 | Scales the source rectangle, preserving its aspect ratio, to align it to the center of the destination rectangle. | 6537| END_SCALE_TO_FIT | 3 | Scales the source rectangle, preserving its aspect ratio, to align it to the lower right corner of the destination rectangle. | 6538 6539## Matrix<sup>12+</sup> 6540 6541Implements a matrix. 6542 6543A 3 x 3 matrix is shown as below. 6544 6545 6546 6547Elements in the matrix from left to right and from top to bottom respectively represent a horizontal scale coefficient, a horizontal skew coefficient, a horizontal translation coefficient, a vertical skew coefficient, a vertical scale coefficient, a vertical translation coefficient, an X-axis perspective coefficient, a Y-axis perspective coefficient, and a perspective scale coefficient. 6548If (x<sub>1</sub>, y<sub>1</sub>) is the source coordinate point, (x<sub>2</sub>, y<sub>2</sub>) is the coordinate point obtained by transforming the source coordinate point using the matrix, then the relationship between the two coordinate points is as follows: 6549 6550 6551 6552### constructor<sup>12+</sup> 6553 6554constructor() 6555 6556Creates a **Matrix** object. 6557 6558**System capability**: SystemCapability.Graphics.Drawing 6559 6560**Example** 6561 6562```ts 6563import { drawing } from '@kit.ArkGraphics2D'; 6564 6565let matrix = new drawing.Matrix(); 6566``` 6567 6568### setRotation<sup>12+</sup> 6569 6570setRotation(degree: number, px: number, py: number): void 6571 6572Sets this matrix as an identity matrix and rotates it by a given degree around the rotation point (px, py). 6573 6574**System capability**: SystemCapability.Graphics.Drawing 6575 6576**Parameters** 6577 6578| Name | Type | Mandatory | Description | 6579| ----------- | ---------------------------------------- | ---- | ------------------- | 6580| degree | number | Yes | Angle to rotate, in degrees. A positive number indicates a clockwise rotation, and a negative number indicates a counterclockwise rotation. The value is a floating point number.| 6581| px | number | Yes | X coordinate of the rotation point. The value is a floating point number. | 6582| py | number | Yes | Y coordinate of the rotation point. The value is a floating point number. | 6583 6584**Error codes** 6585 6586For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6587 6588| ID| Error Message| 6589| ------- | --------------------------------------------| 6590| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6591 6592**Example** 6593 6594```ts 6595import { drawing } from '@kit.ArkGraphics2D'; 6596 6597let matrix = new drawing.Matrix(); 6598matrix.setRotation(90, 100, 100); 6599``` 6600 6601### setScale<sup>12+</sup> 6602 6603setScale(sx: number, sy: number, px: number, py: number): void 6604 6605Sets this matrix as an identity matrix and scales it with the coefficients (sx, sy) at the scale point (px, py). 6606 6607**System capability**: SystemCapability.Graphics.Drawing 6608 6609**Parameters** 6610 6611| Name | Type | Mandatory | Description | 6612| ----------- | ---------------------------------------- | ---- | ------------------- | 6613| sx | number | Yes | Scale coefficient along the X axis. If a negative number is passed in, the matrix is mirrored around y = px before being scaled. The value is a floating point number. | 6614| sy | number | Yes | Scale coefficient along the Y axis. If a negative number is passed in, the matrix is mirrored around x = py before being scaled. The value is a floating point number. | 6615| px | number | Yes | X coordinate of the scale point. The value is a floating point number. | 6616| py | number | Yes | Y coordinate of the scale point. The value is a floating point number. | 6617 6618**Error codes** 6619 6620For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6621 6622| ID| Error Message| 6623| ------- | --------------------------------------------| 6624| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6625 6626**Example** 6627 6628```ts 6629import { drawing } from '@kit.ArkGraphics2D'; 6630 6631let matrix = new drawing.Matrix(); 6632matrix.setScale(100, 100, 150, 150); 6633``` 6634 6635### setTranslation<sup>12+</sup> 6636 6637setTranslation(dx: number, dy: number): void 6638 6639Sets this matrix as an identity matrix and translates it by a given distance (dx, dy). 6640 6641**System capability**: SystemCapability.Graphics.Drawing 6642 6643**Parameters** 6644 6645| Name | Type | Mandatory | Description | 6646| ----------- | ---------------------------------------- | ---- | ------------------- | 6647| dx | number | Yes | Horizontal distance to translate. A positive number indicates a translation towards the positive direction of the X axis, and a negative number indicates a translation towards the negative direction of the X axis. The value is a floating point number. | 6648| dy | number | Yes | Vertical distance to translate. A positive number indicates a translation towards the positive direction of the Y axis, and a negative number indicates a translation towards the negative direction of the Y axis. The value is a floating point number. | 6649 6650**Error codes** 6651 6652For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6653 6654| ID| Error Message| 6655| ------- | --------------------------------------------| 6656| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6657 6658**Example** 6659 6660```ts 6661import { drawing } from '@kit.ArkGraphics2D'; 6662 6663let matrix = new drawing.Matrix(); 6664matrix.setTranslation(100, 100); 6665``` 6666 6667### setMatrix<sup>12+</sup> 6668 6669setMatrix(values: Array\<number>): void 6670 6671Sets parameters for this matrix. 6672 6673**System capability**: SystemCapability.Graphics.Drawing 6674 6675**Parameters** 6676 6677| Name| Type | Mandatory| Description | 6678| ------ | ---------------------------------------------------- | ---- | ---------------- | 6679| values | Array\<number> | Yes | Floating-point array that holds the parameter values, with the array length set to 9. The values in the array respectively represent a horizontal scale coefficient, a horizontal skew coefficient, a horizontal translation coefficient, a vertical skew coefficient, a vertical scale coefficient, a vertical translation coefficient, an X-axis perspective coefficient, a Y-axis perspective coefficient, and a perspective scale coefficient, in ascending order of indexes.| 6680 6681**Error codes** 6682 6683For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6684 6685| ID| Error Message| 6686| ------- | --------------------------------------------| 6687| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 6688 6689**Example** 6690 6691```ts 6692import { drawing } from '@kit.ArkGraphics2D'; 6693 6694let matrix = new drawing.Matrix(); 6695let value : Array<number> = [2, 2, 2, 2, 2, 2, 2, 2, 2]; 6696matrix.setMatrix(value); 6697``` 6698 6699### preConcat<sup>12+</sup> 6700 6701preConcat(matrix: Matrix): void 6702 6703Preconcats the existing matrix with the passed-in matrix. 6704 6705**System capability**: SystemCapability.Graphics.Drawing 6706 6707**Parameters** 6708 6709| Name| Type | Mandatory| Description | 6710| ------ | ---------------------------------------------------- | ---- | ---------------- | 6711| matrix | [Matrix](#matrix12) | Yes | **Matrix** object, which is on the right of a multiplication expression.| 6712 6713**Error codes** 6714 6715For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6716 6717| ID| Error Message| 6718| ------- | --------------------------------------------| 6719| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6720 6721**Example** 6722 6723```ts 6724import { drawing } from '@kit.ArkGraphics2D'; 6725 6726let matrix1 = new drawing.Matrix(); 6727matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 6728let matrix2 = new drawing.Matrix(); 6729matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 6730matrix1.preConcat(matrix2); 6731``` 6732 6733### isEqual<sup>12+</sup> 6734 6735isEqual(matrix: Matrix): Boolean 6736 6737Checks whether this matrix is equal to another matrix. 6738 6739**System capability**: SystemCapability.Graphics.Drawing 6740 6741**Parameters** 6742 6743| Name| Type | Mandatory| Description | 6744| ------ | ---------------------------------------------------- | ---- | ---------------- | 6745| matrix | [Matrix](#matrix12) | Yes | Matrix to compare.| 6746 6747**Return value** 6748 6749| Type | Description | 6750| --------------------------- | -------------------- | 6751| Boolean | Comparison result of the two matrices. The value **true** means that the two matrices are equal, and **false** means the opposite.| 6752 6753**Error codes** 6754 6755For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6756 6757| ID| Error Message| 6758| ------- | --------------------------------------------| 6759| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6760 6761**Example** 6762 6763```ts 6764import { drawing } from '@kit.ArkGraphics2D'; 6765 6766let matrix1 = new drawing.Matrix(); 6767matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 6768let matrix2 = new drawing.Matrix(); 6769matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 6770if (matrix1.isEqual(matrix2)) { 6771 console.info("matrix1 and matrix2 are equal."); 6772} else { 6773 console.info("matrix1 and matrix2 are not equal."); 6774} 6775``` 6776 6777### invert<sup>12+</sup> 6778 6779invert(matrix: Matrix): Boolean 6780 6781Inverts this matrix and returns the result. 6782 6783**System capability**: SystemCapability.Graphics.Drawing 6784 6785**Parameters** 6786 6787| Name| Type | Mandatory| Description | 6788| ------ | ---------------------------------------------------- | ---- | ---------------- | 6789| matrix | [Matrix](#matrix12) | Yes | **Matrix** object used to store the inverted matrix.| 6790 6791**Return value** 6792 6793| Type | Description | 6794| --------------------------- | -------------------- | 6795| Boolean | Result indicating whether the matrix is revertible. The value **true** means that the matrix is revertible and the **matrix** object is filled with the inverted matrix, and **false** means that the matrix is not revertible and the **matrix** object is filled with the current matrix (not changed).| 6796 6797**Error codes** 6798 6799For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6800 6801| ID| Error Message| 6802| ------- | --------------------------------------------| 6803| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6804 6805**Example** 6806 6807```ts 6808import { drawing } from '@kit.ArkGraphics2D'; 6809 6810let matrix1 = new drawing.Matrix(); 6811matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 6812let matrix2 = new drawing.Matrix(); 6813matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 6814if (matrix1.invert(matrix2)) { 6815 console.info("matrix1 is invertible and matrix2 is set as an inverse matrix of the matrix1."); 6816} else { 6817 console.info("matrix1 is not invertible and matrix2 is not changed."); 6818} 6819``` 6820 6821### isIdentity<sup>12+</sup> 6822 6823isIdentity(): Boolean 6824 6825Checks whether this matrix is an identity matrix. 6826 6827**System capability**: SystemCapability.Graphics.Drawing 6828 6829**Return value** 6830 6831| Type | Description | 6832| --------------------------- | -------------------- | 6833| Boolean | Result indicating whether the matrix is an identity matrix. The value **true** means that the matrix is an identity matrix, and **false** means the opposite.| 6834 6835**Example** 6836 6837```ts 6838import { drawing } from '@kit.ArkGraphics2D'; 6839 6840let matrix = new drawing.Matrix(); 6841if (matrix.isIdentity()) { 6842 console.info("matrix is identity."); 6843} else { 6844 console.info("matrix is not identity."); 6845} 6846``` 6847 6848### getValue<sup>12+</sup> 6849 6850getValue(index: number): number 6851 6852Obtains the value of a given index in this matrix. The index ranges from 0 to 8. 6853 6854**System capability**: SystemCapability.Graphics.Drawing 6855 6856**Parameters** 6857 6858| Name | Type | Mandatory| Description | 6859| --------------- | ------- | ---- | ----------------------------------------------------------- | 6860| index | number | Yes | Index. The value is an integer ranging from 0 to 8.| 6861 6862**Return value** 6863 6864| Type | Description | 6865| --------------------- | -------------- | 6866| number | Value obtained, which is an integer.| 6867 6868**Error codes** 6869 6870For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6871 6872| ID| Error Message| 6873| ------- | --------------------------------------------| 6874| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.| 6875 6876**Example** 6877 6878```ts 6879import {drawing} from "@kit.ArkGraphics2D" 6880let matrix = new drawing.Matrix(); 6881for (let i = 0; i < 9; i++) { 6882 console.info("matrix "+matrix.getValue(i).toString()); 6883} 6884``` 6885 6886### postRotate<sup>12+</sup> 6887 6888postRotate(degree: number, px: number, py: number): void 6889 6890Post multiplies this matrix by a matrix that is derived from an identity matrix after it has been rotated by a given degree around the rotation point (px, py). 6891 6892**System capability**: SystemCapability.Graphics.Drawing 6893 6894**Parameters** 6895 6896| Name | Type | Mandatory| Description | 6897| --------------- | ------- | ---- | ----------------------------------------------------------- | 6898| degree | number | Yes | Angle to rotate, in degrees. A positive number indicates a clockwise rotation, and a negative number indicates a counterclockwise rotation. The value is a floating point number.| 6899| px | number | Yes | X coordinate of the rotation point. The value is a floating point number.| 6900| py | number | Yes | Y coordinate of the rotation point. The value is a floating point number.| 6901 6902**Error codes** 6903 6904For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6905 6906| ID| Error Message| 6907| ------- | --------------------------------------------| 6908| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6909 6910**Example** 6911 6912```ts 6913import {drawing} from "@kit.ArkGraphics2D" 6914let matrix = new drawing.Matrix(); 6915let degree: number = 2; 6916let px: number = 3; 6917let py: number = 4; 6918matrix.postRotate(degree, px, py); 6919console.info("matrix= "+matrix.getAll().toString()); 6920``` 6921 6922### postScale<sup>12+</sup> 6923 6924postScale(sx: number, sy: number, px: number, py: number): void 6925 6926Post multiplies this matrix by a matrix that is derived from an identity matrix after it has been scaled with the coefficient (sx, sy) at the scale point (px, py). 6927 6928**System capability**: SystemCapability.Graphics.Drawing 6929 6930**Parameters** 6931 6932| Name | Type | Mandatory| Description | 6933| --------------- | ------- | ---- | ----------------------------------------------------------- | 6934| sx | number | Yes | Scale coefficient along the X axis. If a negative number is passed in, the matrix is mirrored around y = px before being scaled. The value is a floating point number.| 6935| sy | number | Yes | Scale coefficient along the Y axis. If a negative number is passed in, the matrix is mirrored around x = py before being scaled. The value is a floating point number.| 6936| px | number | Yes | X coordinate of the scale point. The value is a floating point number.| 6937| py | number | Yes | Y coordinate of the scale point. The value is a floating point number.| 6938 6939**Error codes** 6940 6941For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6942 6943| ID| Error Message| 6944| ------- | --------------------------------------------| 6945| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6946 6947**Example** 6948 6949```ts 6950import {drawing} from "@kit.ArkGraphics2D" 6951let matrix = new drawing.Matrix(); 6952let sx: number = 2; 6953let sy: number = 0.5; 6954let px: number = 1; 6955let py: number = 1; 6956matrix.postScale(sx, sy, px, py); 6957console.info("matrix= "+matrix.getAll().toString()); 6958``` 6959 6960### postTranslate<sup>12+</sup> 6961 6962postTranslate(dx: number, dy: number): void 6963 6964Post multiplies this matrix by a matrix that is derived from an identity matrix after it has been translated by a given distance (dx, dy). 6965 6966**System capability**: SystemCapability.Graphics.Drawing 6967 6968**Parameters** 6969 6970| Name | Type | Mandatory| Description | 6971| --------------- | ------- | ---- | ----------------------------------------------------------- | 6972| dx | number | Yes | Horizontal distance to translate. A positive number indicates a translation towards the positive direction of the X axis, and a negative number indicates a translation towards the negative direction of the X axis. The value is a floating point number.| 6973| dy | number | Yes | Vertical distance to translate. A positive number indicates a translation towards the positive direction of the Y axis, and a negative number indicates a translation towards the negative direction of the Y axis. The value is a floating point number.| 6974 6975**Error codes** 6976 6977For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 6978 6979| ID| Error Message| 6980| ------- | --------------------------------------------| 6981| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 6982 6983**Example** 6984 6985```ts 6986import {drawing} from "@kit.ArkGraphics2D" 6987let matrix = new drawing.Matrix(); 6988let dx: number = 3; 6989let dy: number = 4; 6990matrix.postTranslate(dx, dy); 6991console.info("matrix= "+matrix.getAll().toString()); 6992``` 6993 6994### preRotate<sup>12+</sup> 6995 6996preRotate(degree: number, px: number, py: number): void 6997 6998Premultiplies this matrix by a matrix that is derived from an identity matrix after it has been rotated by a given degree around the rotation point (px, py). 6999 7000**System capability**: SystemCapability.Graphics.Drawing 7001 7002**Parameters** 7003 7004| Name | Type | Mandatory| Description | 7005| --------------- | ------- | ---- | ----------------------------------------------------------- | 7006| degree | number | Yes | Angle to rotate, in degrees. A positive number indicates a clockwise rotation, and a negative number indicates a counterclockwise rotation. The value is a floating point number.| 7007| px | number | Yes | X coordinate of the rotation point. The value is a floating point number.| 7008| py | number | Yes | Y coordinate of the rotation point. The value is a floating point number.| 7009 7010**Error codes** 7011 7012For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7013 7014| ID| Error Message| 7015| ------- | --------------------------------------------| 7016| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7017 7018**Example** 7019 7020```ts 7021import {drawing} from "@kit.ArkGraphics2D" 7022let matrix = new drawing.Matrix(); 7023let degree: number = 2; 7024let px: number = 3; 7025let py: number = 4; 7026matrix.preRotate(degree, px, py); 7027console.info("matrix= "+matrix.getAll().toString()); 7028``` 7029 7030### preScale<sup>12+</sup> 7031 7032preScale(sx: number, sy: number, px: number, py: number): void 7033 7034Premultiplies this matrix by a matrix that is derived from an identity matrix after it has been scaled with the coefficient (sx, sy) at the scale point (px, py). 7035 7036**System capability**: SystemCapability.Graphics.Drawing 7037 7038**Parameters** 7039 7040| Name | Type | Mandatory| Description | 7041| --------------- | ------- | ---- | ----------------------------------------------------------- | 7042| sx | number | Yes | Scale coefficient along the X axis. If a negative number is passed in, the matrix is mirrored around y = px before being scaled. The value is a floating point number.| 7043| sy | number | Yes | Scale coefficient along the Y axis. If a negative number is passed in, the matrix is mirrored around x = py before being scaled. The value is a floating point number.| 7044| px | number | Yes | X coordinate of the scale point. The value is a floating point number.| 7045| py | number | Yes | Y coordinate of the scale point. The value is a floating point number.| 7046 7047**Error codes** 7048 7049For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7050 7051| ID| Error Message| 7052| ------- | --------------------------------------------| 7053| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7054 7055**Example** 7056 7057```ts 7058import {drawing} from "@kit.ArkGraphics2D" 7059let matrix = new drawing.Matrix(); 7060let sx: number = 2; 7061let sy: number = 0.5; 7062let px: number = 1; 7063let py: number = 1; 7064matrix.preScale(sx, sy, px, py); 7065console.info("matrix"+matrix.getAll().toString()); 7066``` 7067 7068### preTranslate<sup>12+</sup> 7069 7070preTranslate(dx: number, dy: number): void 7071 7072Premultiplies a matrix by a matrix that is derived from an identity matrix after it has been translated by a given distance (dx, dy). 7073 7074**System capability**: SystemCapability.Graphics.Drawing 7075 7076**Parameters** 7077 7078| Name | Type | Mandatory| Description | 7079| --------------- | ------- | ---- | ----------------------------------------------------------- | 7080| dx | number | Yes | Horizontal distance to translate. A positive number indicates a translation towards the positive direction of the X axis, and a negative number indicates a translation towards the negative direction of the X axis. The value is a floating point number.| 7081| dy | number | Yes | Vertical distance to translate. A positive number indicates a translation towards the positive direction of the Y axis, and a negative number indicates a translation towards the negative direction of the Y axis. The value is a floating point number.| 7082 7083**Error codes** 7084 7085For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7086 7087| ID| Error Message| 7088| ------- | --------------------------------------------| 7089| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7090 7091**Example** 7092 7093```ts 7094import {drawing} from "@kit.ArkGraphics2D" 7095let matrix = new drawing.Matrix(); 7096let dx: number = 3; 7097let dy: number = 4; 7098matrix.preTranslate(dx, dy); 7099console.info("matrix"+matrix.getAll().toString()); 7100``` 7101 7102### reset<sup>12+</sup> 7103 7104reset(): void 7105 7106Resets this matrix to an identity matrix. 7107 7108**System capability**: SystemCapability.Graphics.Drawing 7109 7110**Example** 7111 7112```ts 7113import {drawing} from "@kit.ArkGraphics2D" 7114let matrix = new drawing.Matrix(); 7115matrix.postScale(2, 3, 4, 5); 7116matrix.reset(); 7117console.info("matrix= "+matrix.getAll().toString()); 7118``` 7119 7120### mapPoints<sup>12+</sup> 7121 7122mapPoints(src: Array\<common2D.Point>): Array\<common2D.Point> 7123 7124Maps a source point array to a destination point array by means of matrix transformation. 7125 7126**System capability**: SystemCapability.Graphics.Drawing 7127 7128**Parameters** 7129 7130| Name | Type | Mandatory| Description | 7131| --------------- | ------- | ---- | ----------------------------------------------------------- | 7132| src | Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Yes | Array of source points.| 7133 7134**Return value** 7135 7136| Type | Description | 7137| --------------------- | -------------- | 7138| Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Array of points obtained.| 7139 7140**Error codes** 7141 7142For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7143 7144| ID| Error Message| 7145| ------- | --------------------------------------------| 7146| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7147 7148**Example** 7149 7150```ts 7151import {drawing,common2D} from "@kit.ArkGraphics2D" 7152let src: Array<common2D.Point> = []; 7153src.push({x: 15, y: 20}); 7154src.push({x: 20, y: 15}); 7155src.push({x: 30, y: 10}); 7156let matrix = new drawing.Matrix(); 7157let dst: Array<common2D.Point> = matrix.mapPoints(src); 7158console.info("matrix= src: "+JSON.stringify(src)); 7159console.info("matrix= dst: "+JSON.stringify(dst)); 7160``` 7161 7162### getAll<sup>12+</sup> 7163 7164getAll(): Array\<number> 7165 7166Obtains all element values of this matrix. 7167 7168**System capability**: SystemCapability.Graphics.Drawing 7169 7170**Return value** 7171 7172| Type | Description | 7173| --------------------- | -------------- | 7174| Array\<number> | Array of matrix values obtained. The length is 9. Each value is a floating point number.| 7175 7176**Example** 7177 7178```ts 7179import {drawing} from "@kit.ArkGraphics2D" 7180let matrix = new drawing.Matrix(); 7181console.info("matrix "+ matrix.getAll()); 7182``` 7183 7184### mapRect<sup>12+</sup> 7185 7186mapRect(dst: common2D.Rect, src: common2D.Rect): boolean 7187 7188Sets the destination rectangle to the bounding rectangle of the shape obtained after transforming the source rectangle with a matrix transformation. As shown in the figure below, the blue rectangle represents the source rectangle, and the yellow rectangle is the shape obtained after a matrix transformation is applied to the source rectangle. Since the edges of the yellow rectangle are not aligned with the coordinate axes, it cannot be represented by a rectangle object. To address this issue, a destination rectangle (black rectangle) is defined as the bounding rectangle. 7189 7190 7191 7192**System capability**: SystemCapability.Graphics.Drawing 7193 7194**Parameters** 7195 7196| Name | Type | Mandatory| Description | 7197| --------------- | ------- | ---- | ----------------------------------------------------------- | 7198| dst | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | **Rectangle** object, which is used to store the bounding rectangle.| 7199| src |[common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Source rectangle.| 7200 7201**Return value** 7202 7203| Type | Description | 7204| --------------------- | -------------- | 7205| boolean | Result indicating whether the shape, transformed from the source rectangle via a matrix transformation, retains a rectangular form. The value **true** means that the shape retains a rectangular form, and **false** means the opposite.| 7206 7207**Error codes** 7208 7209For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7210 7211| ID| Error Message| 7212| ------- | --------------------------------------------| 7213| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7214 7215**Example** 7216 7217```ts 7218import {drawing,common2D} from "@kit.ArkGraphics2D" 7219let dst: common2D.Rect = { left: 100, top: 20, right: 130, bottom: 60 }; 7220let src: common2D.Rect = { left: 100, top: 80, right: 130, bottom: 120 }; 7221let matrix = new drawing.Matrix(); 7222if (matrix.mapRect(dst, src)) { 7223 console.info("matrix= dst "+JSON.stringify(dst)); 7224} 7225``` 7226 7227### setRectToRect<sup>12+</sup> 7228 7229setRectToRect(src: common2D.Rect, dst: common2D.Rect, scaleToFit: ScaleToFit): boolean 7230 7231Sets this matrix to a transformation matrix that maps a source rectangle to a destination rectangle. 7232 7233**System capability**: SystemCapability.Graphics.Drawing 7234 7235**Parameters** 7236 7237| Name | Type | Mandatory| Description | 7238| --------------- | ------- | ---- | ----------------------------------------------------------- | 7239| src | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Source rectangle.| 7240| dst | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Destination rectangle.| 7241| scaleToFit | [ScaleToFit](#scaletofit12) | Yes | Mapping mode from the source rectangle to the target rectangle.| 7242 7243**Return value** 7244 7245| Type | Description | 7246| --------------------- | -------------- | 7247| boolean | Result indicating whether the matrix can represent the mapping between rectangles. The value **true** means that the matrix can represent the mapping, and **false** means the opposite. In particular, if either the width or the height of the source rectangle is less than or equal to 0, the API returns **false** and sets the matrix to an identity matrix. If either the width or height of the destination rectangle is less than or equal to 0, the API returns **true** and sets the matrix to a matrix with all values 0, except for a perspective scaling coefficient of 1.| 7248 7249**Error codes** 7250 7251For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7252 7253| ID| Error Message| 7254| ------- | --------------------------------------------| 7255| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 7256 7257**Example** 7258 7259```ts 7260import {drawing,common2D} from "@kit.ArkGraphics2D" 7261let src: common2D.Rect = { left: 100, top: 100, right: 300, bottom: 300 }; 7262let dst: common2D.Rect = { left: 200, top: 200, right: 600, bottom: 600 }; 7263let scaleToFit: drawing.ScaleToFit = drawing.ScaleToFit.FILL_SCALE_TO_FIT 7264let matrix = new drawing.Matrix(); 7265if (matrix.setRectToRect(src, dst, scaleToFit)) { 7266 console.info("matrix"+matrix.getAll().toString()); 7267} 7268``` 7269 7270### setPolyToPoly<sup>12+</sup> 7271 7272setPolyToPoly(src: Array\<common2D.Point>, dst: Array\<common2D.Point>, count: number): boolean 7273 7274Sets this matrix to a transformation matrix that maps the source point array to the destination point array. 7275 7276**System capability**: SystemCapability.Graphics.Drawing 7277 7278**Parameters** 7279 7280| Name | Type | Mandatory| Description | 7281| --------------- | ------- | ---- | ----------------------------------------------------------- | 7282| src | Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Yes | Array of source points. The array length must be the same as the value of **count**.| 7283| dst | Array\<[common2D.Point](js-apis-graphics-common2D.md#point)> | Yes | Array of destination points. The array length must be the same as the value of **count**.| 7284| count | number | Yes | Number of points in each array. The value is an integer.| 7285 7286**Return value** 7287 7288| Type | Description | 7289| --------------------- | -------------- | 7290| boolean | Result indicating whether the setting is successful. The value **true** means that the setting is successful, and **false** means the opposite.| 7291 7292**Error codes** 7293 7294For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7295 7296| ID| Error Message| 7297| ------- | --------------------------------------------| 7298| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7299 7300**Example** 7301 7302```ts 7303import {drawing,common2D} from "@kit.ArkGraphics2D" 7304let srcPoints: Array<common2D.Point> = [ {x: 10, y: 20}, {x: 200, y: 150} ]; 7305let dstPoints: Array<common2D.Point> = [{ x:0, y: 10 }, { x:300, y: 600 }]; 7306let matrix = new drawing.Matrix(); 7307if (matrix.setPolyToPoly(srcPoints, dstPoints, 2)) { 7308 console.info("matrix"+matrix.getAll().toString()); 7309} 7310``` 7311 7312## RoundRect<sup>12+</sup> 7313 7314Implements a rounded rectangle. 7315 7316### constructor<sup>12+</sup> 7317 7318constructor(rect: common2D.Rect, xRadii: number, yRadii: number) 7319 7320A constructor used to create a **RoundRect** object. A rounded rectangle is created when both **xRadii** and **yRadii** are greater than 0. Otherwise, only a rectangle is created. 7321 7322**System capability**: SystemCapability.Graphics.Drawing 7323 7324**Parameters** 7325 7326| Name | Type | Mandatory | Description | 7327| ----------- | ---------------------------------------- | ---- | ------------------- | 7328| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes | Rectangle that encloses the rounded rectangle to create. | 7329| xRadii | number | Yes | Radius of the rounded corner on the X axis. The value is a floating point number. A negative number is invalid. | 7330| yRadii | number | Yes | Radius of the rounded corner on the Y axis. The value is a floating point number. A negative number is invalid. | 7331 7332**Error codes** 7333 7334For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7335 7336| ID| Error Message| 7337| ------- | --------------------------------------------| 7338| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7339 7340**Example** 7341 7342```ts 7343import { common2D, drawing } from '@kit.ArkGraphics2D'; 7344 7345let rect: common2D.Rect = {left : 100, top : 100, right : 500, bottom : 300}; 7346let roundRect = new drawing.RoundRect(rect, 50, 50); 7347``` 7348### setCorner<sup>12+</sup> 7349 7350setCorner(pos: CornerPos, x: number, y: number): void 7351 7352Sets the radii of the specified rounded corner in this rounded rectangle. 7353 7354**System capability**: SystemCapability.Graphics.Drawing 7355 7356**Parameters** 7357 7358| Name | Type | Mandatory| Description | 7359| -------- | -------------------------------------------- | ---- | ------------------------------- | 7360| pos | [CornerPos](#cornerpos12) | Yes | Position of the rounded corner. | 7361| x | number | Yes | Radius of the rounded corner on the X axis. The value is a floating point number.| 7362| y | number | Yes | Radius of the rounded corner on the Y axis. The value is a floating point number.| 7363 7364**Error codes** 7365 7366For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7367 7368| ID| Error Message| 7369| ------- | --------------------------------------------| 7370| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 7371 7372**Example** 7373 7374```ts 7375import { drawing } from '@kit.ArkGraphics2D'; 7376let roundRect : drawing.RoundRect = new drawing.RoundRect({left: 0, top: 0, right: 300, bottom: 300}, 50, 50); 7377roundRect.setCorner(drawing.CornerPos.TOP_LEFT_POS, 150, 150); 7378``` 7379 7380### getCorner<sup>12+</sup> 7381 7382getCorner(pos: CornerPos): common2D.Point 7383 7384Obtains the radii of the specified rounded corner in this rounded rectangle. 7385 7386**System capability**: SystemCapability.Graphics.Drawing 7387 7388**Parameters** 7389 7390| Name | Type | Mandatory| Description | 7391| -------- | -------------------------------------------- | ---- | ------------------------------- | 7392| pos | [CornerPos](#cornerpos12) | Yes | Position of the rounded corner. | 7393 7394**Return value** 7395 7396| Type | Description | 7397| --------------------- | -------------- | 7398| [common2D.Point](js-apis-graphics-common2D.md#point) | Point. The horizontal coordinate indicates the radius of the rounded corner on the X axis, and the vertical coordinate indicates the radius on the Y axis.| 7399 7400**Error codes** 7401 7402For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7403 7404| ID| Error Message| 7405| ------- | --------------------------------------------| 7406| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 7407 7408**Example** 7409 7410```ts 7411import { drawing } from '@kit.ArkGraphics2D'; 7412let roundRect : drawing.RoundRect = new drawing.RoundRect({left: 0, top: 0, right: 300, bottom: 300}, 50, 50); 7413let cornerRadius = roundRect.getCorner(drawing.CornerPos.BOTTOM_LEFT_POS); 7414console.info("getCorner---"+cornerRadius.x) 7415console.info("getCorner---"+cornerRadius.y) 7416``` 7417 7418### offset<sup>12+</sup> 7419 7420offset(dx: number, dy: number): void 7421 7422Translates this rounded rectangle by an offset along the X axis and Y axis. 7423 7424**System capability**: SystemCapability.Graphics.Drawing 7425 7426**Parameters** 7427 7428| Name | Type | Mandatory| Description | 7429| -------- | -------------------------------------------- | ---- | ------------------------------- | 7430| dx | number | Yes | Horizontal distance to translate. A positive number indicates a translation towards the positive direction of the X axis, and a negative number indicates a translation towards the negative direction of the X axis. The value is a floating point number. | 7431| dy | number | Yes | Vertical distance to translate. A positive number indicates a translation towards the positive direction of the Y axis, and a negative number indicates a translation towards the negative direction of the Y axis. The value is a floating point number. | 7432 7433**Error codes** 7434 7435For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7436 7437| ID| Error Message| 7438| ------- | --------------------------------------------| 7439| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7440 7441**Example** 7442 7443```ts 7444import { drawing } from '@kit.ArkGraphics2D'; 7445let roundRect : drawing.RoundRect = new drawing.RoundRect({left: 0, top: 0, right: 300, bottom: 300}, 50, 50); 7446roundRect.offset(100, 100); 7447``` 7448 7449## Region<sup>12+</sup> 7450 7451Describes a region, which is used to describe the region where the shape can be drawn. 7452 7453### isPointContained<sup>12+</sup> 7454 7455isPointContained(x: number, y: number) : boolean 7456 7457Checks whether a point is contained in this region. 7458 7459**System capability**: SystemCapability.Graphics.Drawing 7460 7461**Parameters** 7462 7463| Name| Type | Mandatory| Description | 7464| ------ | ------ | ---- | ----------------------- | 7465| x | number | Yes | X coordinate of the point. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7466| y | number | Yes | Y coordinate of the point. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7467 7468**Return value** 7469 7470| Type | Description | 7471| ------- | -------------- | 7472| boolean | Result indicating whether the point is contained in the region. The value **true** means that the point is contained, and **false** means the opposite.| 7473 7474**Error codes** 7475 7476For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7477 7478| ID| Error Message| 7479| ------- | --------------------------------------------| 7480| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7481 7482**Example** 7483 7484```ts 7485import { RenderNode } from '@kit.ArkUI'; 7486class DrawingRenderNode extends RenderNode { 7487 draw(context : DrawContext) { 7488 const canvas = context.canvas; 7489 const pen = new drawing.Pen(); 7490 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7491 pen.setStrokeWidth(10); 7492 canvas.attachPen(pen); 7493 let region = new drawing.Region(); 7494 region.setRect(100, 100, 400, 400); 7495 let flag: boolean = false; 7496 flag = region.isPointContained(200,200); 7497 console.info("region isPointContained : " + flag); 7498 canvas.drawPoint(200,200); 7499 canvas.drawRegion(region); 7500 canvas.detachPen(); 7501 } 7502} 7503``` 7504 7505### isRegionContained<sup>12+</sup> 7506 7507isRegionContained(other: Region) : boolean 7508 7509Checks whether another region is contained in this region. 7510 7511**System capability**: SystemCapability.Graphics.Drawing 7512 7513**Parameters** 7514 7515| Name| Type | Mandatory| Description | 7516| ------ | ------ | ---- | ----------------------- | 7517| other | [Region](#region12) | Yes | **Region** object.| 7518 7519**Return value** 7520 7521| Type | Description | 7522| ------- | -------------- | 7523| boolean | Result indicating whether the other region is contained in the current region. The value **true** means that the other region is contained, and **false** means the opposite.| 7524 7525**Error codes** 7526 7527For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7528 7529| ID| Error Message| 7530| ------- | --------------------------------------------| 7531| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7532 7533**Example** 7534 7535```ts 7536import { RenderNode } from '@kit.ArkUI'; 7537class DrawingRenderNode extends RenderNode { 7538 draw(context : DrawContext) { 7539 const canvas = context.canvas; 7540 const pen = new drawing.Pen(); 7541 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7542 pen.setStrokeWidth(10); 7543 canvas.attachPen(pen); 7544 let region = new drawing.Region(); 7545 let other = new drawing.Region(); 7546 region.setRect(100, 100, 400, 400); 7547 other.setRect(150, 150, 250 ,250); 7548 let flag: boolean = false; 7549 flag = region.isRegionContained(other); 7550 console.info("region isRegionContained : " + flag); 7551 canvas.drawRegion(region); 7552 canvas.drawRegion(other); 7553 canvas.detachPen(); 7554 } 7555} 7556``` 7557 7558### op<sup>12+</sup> 7559 7560op(region: Region, regionOp: RegionOp) : boolean 7561 7562Performs an operation on this region and another region, and stores the resulting region in this **Region** object. 7563 7564**System capability**: SystemCapability.Graphics.Drawing 7565 7566**Parameters** 7567 7568| Name| Type | Mandatory| Description | 7569| ------ | ------ | ---- | ----------------------- | 7570| region | [Region](#region12) | Yes | **Region** object.| 7571| regionOp | [RegionOp](#regionop12) | Yes | Operation mode of the region.| 7572 7573**Return value** 7574 7575| Type | Description | 7576| ------- | -------------- | 7577| boolean | Result indicating whether the resulting region is stored in the current **Region** object. The value **true** means that the resulting region is stored in the current **Region** object, and **false** means the opposite.| 7578 7579**Error codes** 7580 7581For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7582 7583| ID| Error Message| 7584| ------- | --------------------------------------------| 7585| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7586 7587**Example** 7588 7589```ts 7590import { RenderNode } from '@kit.ArkUI'; 7591class DrawingRenderNode extends RenderNode { 7592 draw(context : DrawContext) { 7593 const canvas = context.canvas; 7594 const pen = new drawing.Pen(); 7595 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7596 pen.setStrokeWidth(10); 7597 canvas.attachPen(pen); 7598 let region = new drawing.Region(); 7599 region.setRect(200, 200, 400, 400); 7600 let othregion = new drawing.Region(); 7601 othregion.setRect(110, 110, 240, 240); 7602 let flag: boolean = false; 7603 flag = region.op(othregion,drawing.RegionOp.REPLACE); 7604 console.info("region op : " + flag); 7605 canvas.drawRegion(region); 7606 canvas.detachPen(); 7607 } 7608} 7609``` 7610 7611### quickReject<sup>12+</sup> 7612 7613quickReject(left: number, top: number, right: number, bottom: number) : boolean 7614 7615Checks whether a rectangle do not intersect with this region. Actually, this API determines whether the rectangle does not intersect with the bounding rectangle of the region, and therefore the result may not be accurate. 7616 7617**System capability**: SystemCapability.Graphics.Drawing 7618 7619**Parameters** 7620 7621| Name| Type | Mandatory| Description | 7622| ------ | ------ | ---- | ----------------------- | 7623| left | number | Yes | Left position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7624| top | number | Yes | Top position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7625| right | number | Yes | Right position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7626| bottom | number | Yes | Bottom position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7627 7628**Return value** 7629 7630| Type | Description | 7631| ------- | -------------- | 7632| boolean | Check result. The value **true** means that the two do not intersect, and **false** means the opposite.| 7633 7634**Error codes** 7635 7636For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7637 7638| ID| Error Message| 7639| ------- | --------------------------------------------| 7640| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7641 7642**Example** 7643 7644```ts 7645import { RenderNode } from '@kit.ArkUI'; 7646class DrawingRenderNode extends RenderNode { 7647 draw(context : DrawContext) { 7648 const canvas = context.canvas; 7649 const pen = new drawing.Pen(); 7650 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7651 pen.setStrokeWidth(10); 7652 canvas.attachPen(pen); 7653 let region = new drawing.Region(); 7654 region.setRect(100, 100, 400, 400); 7655 let flag: boolean = false; 7656 flag = region.quickReject(50, 50, 70, 70); 7657 console.info("region quickReject : " + flag); 7658 canvas.drawRegion(region); 7659 canvas.detachPen(); 7660 } 7661} 7662``` 7663 7664### setPath<sup>12+</sup> 7665 7666setPath(path: Path, clip: Region) : boolean 7667 7668Sets a region that matches the outline of a path within the cropping area. 7669 7670**System capability**: SystemCapability.Graphics.Drawing 7671 7672**Parameters** 7673 7674| Name| Type | Mandatory| Description | 7675| ------ | ------ | ---- | ----------------------- | 7676| path | [Path](#path) | Yes | **Path** object.| 7677| clip | [Region](#region12) | Yes | **Region** object.| 7678 7679**Return value** 7680 7681| Type | Description | 7682| ------- | -------------- | 7683| boolean | Result of the setting operation. The value **true** means that the setting is successful, and **false** means the opposite.| 7684 7685**Error codes** 7686 7687For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7688 7689| ID| Error Message| 7690| ------- | --------------------------------------------| 7691| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7692 7693**Example** 7694 7695```ts 7696import { RenderNode } from '@kit.ArkUI'; 7697class DrawingRenderNode extends RenderNode { 7698 draw(context : DrawContext) { 7699 const canvas = context.canvas; 7700 const pen = new drawing.Pen(); 7701 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7702 pen.setStrokeWidth(10); 7703 canvas.attachPen(pen); 7704 let region = new drawing.Region(); 7705 let path = new drawing.Path(); 7706 region.setRect(100, 100, 400, 400); 7707 path.arcTo(50, 50, 300, 300, 0, 359); 7708 let flag: boolean = false; 7709 flag = region.setPath(path,region); 7710 console.info("region setPath : " + flag); 7711 canvas.drawRegion(region); 7712 canvas.detachPen(); 7713 } 7714} 7715``` 7716 7717### setRect<sup>12+</sup> 7718 7719setRect(left: number, top: number, right: number, bottom: number) : boolean 7720 7721Sets a rectangle. 7722 7723**System capability**: SystemCapability.Graphics.Drawing 7724 7725**Parameters** 7726 7727| Name| Type | Mandatory| Description | 7728| ------ | ------ | ---- | ----------------------- | 7729| left | number | Yes | Left position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7730| top | number | Yes | Top position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7731| right | number | Yes | Right position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7732| bottom | number | Yes | Bottom position of the rectangle. The value must be an integer. If a decimal is passed in, the decimal part is rounded off.| 7733 7734**Return value** 7735 7736| Type | Description | 7737| ------- | -------------- | 7738| boolean | Result of the setting operation. The value **true** means that the setting is successful, and **false** means the opposite.| 7739 7740**Error codes** 7741 7742For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7743 7744| ID| Error Message| 7745| ------- | --------------------------------------------| 7746| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7747 7748**Example** 7749 7750```ts 7751import { RenderNode } from '@kit.ArkUI'; 7752class DrawingRenderNode extends RenderNode { 7753 draw(context : DrawContext) { 7754 const canvas = context.canvas; 7755 const pen = new drawing.Pen(); 7756 pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 7757 pen.setStrokeWidth(10); 7758 canvas.attachPen(pen); 7759 let region = new drawing.Region(); 7760 let flag: boolean = false; 7761 flag = region.setRect(50, 50, 300, 300); 7762 console.info("region setRect : " + flag); 7763 canvas.drawRegion(region); 7764 canvas.detachPen(); 7765 } 7766} 7767``` 7768 7769## TileMode<sup>12+</sup> 7770 7771Enumerates the tile modes of the shader effect. 7772 7773**System capability**: SystemCapability.Graphics.Drawing 7774 7775| Name | Value | Description | 7776| ---------------------- | ---- | ------------------------------ | 7777| CLAMP | 0 | Replicates the edge color if the shader effect draws outside of its original boundary.| 7778| REPEAT | 1 | Repeats the shader effect in both horizontal and vertical directions.| 7779| MIRROR | 2 | Repeats the shader effect in both horizontal and vertical directions, alternating mirror images.| 7780| DECAL | 3 | Renders the shader effect only within the original boundary.| 7781 7782## ShaderEffect<sup>12+</sup> 7783 7784Implements the shader effect. After a shader effect is set for a pen or brush, the shader effect instead of the color attribute is used for drawing. In this case, the alpha value set for the pen or brush still takes effect. 7785 7786### createColorShader<sup>12+</sup> 7787 7788static createColorShader(color: number): ShaderEffect 7789 7790Creates a **ShaderEffect** object with a single color. 7791 7792**System capability**: SystemCapability.Graphics.Drawing 7793 7794**Parameters** 7795 7796| Name| Type | Mandatory| Description | 7797| ------ | -------------------------------------------------- | ---- | -------------- | 7798| color | number | Yes | Color in the ARGB format. The value is a 32-bit unsigned integer.| 7799 7800**Return value** 7801 7802| Type | Description | 7803| ------- | ------------------------- | 7804| [ShaderEffect](#shadereffect12) | **ShaderEffect** object with a single color.| 7805 7806**Error codes** 7807 7808For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7809 7810| ID| Error Message| 7811| ------- | --------------------------------------------| 7812| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 7813 7814**Example** 7815 7816```ts 7817import { drawing } from '@kit.ArkGraphics2D'; 7818 7819let shaderEffect = drawing.ShaderEffect.createColorShader(0xFFFF0000); 7820``` 7821 7822### createLinearGradient<sup>12+</sup> 7823 7824static createLinearGradient(startPt: common2D.Point, endPt: common2D.Point, colors: Array 7825\<number>, mode: TileMode, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect 7826 7827Creates a **ShaderEffect** object that generates a linear gradient between two points. 7828 7829**System capability**: SystemCapability.Graphics.Drawing 7830 7831**Parameters** 7832 7833| Name| Type | Mandatory| Description | 7834| ------ | -------------------------------------------------- | ---- | -------------- | 7835| startPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Start point.| 7836| endPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | End point.| 7837| colors | Array\<number> | Yes | Array of colors to distribute between the two points. The values in the array are 32-bit (ARGB) unsigned integers.| 7838| mode | [TileMode](#tilemode12) | Yes | Tile mode of the shader effect.| 7839| pos | Array\<number> \|null| No | Relative position of each color in the color array. The array length must be the same as that of **colors**. The first element in the array must be 0.0, the last element must be 1.0, and the middle elements must be between 0.0 and 1.0 and increase by index. The default value is null, indicating that colors are evenly distributed between the two points.| 7840| matrix | [Matrix](#matrix12) \| null | No | **Matrix** object used to perform matrix transformation on the shader effect. The default value is null, indicating the identity matrix.| 7841 7842 7843 7844The preceding figure shows the display effect when the **colors** array is set to red, green, and blue and the **pos** array is set to 0.0, 0.75, and 1.0. The triangle subscript is the relative position of a color between the start point and end point. Gradient colors are used between them. 7845 7846**Return value** 7847 7848| Type | Description | 7849| ------- | ------------------------- | 7850| [ShaderEffect](#shadereffect12) | **ShaderEffect** object created.| 7851 7852**Error codes** 7853 7854For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7855 7856| ID| Error Message| 7857| ------- | --------------------------------------------| 7858| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 7859 7860**Example** 7861 7862```ts 7863import { common2D,drawing } from '@kit.ArkGraphics2D'; 7864 7865let startPt: common2D.Point = { x: 100, y: 100 }; 7866let endPt: common2D.Point = { x: 300, y: 300 }; 7867let shaderEffect =drawing.ShaderEffect.createLinearGradient(startPt, endPt, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 7868``` 7869 7870### createRadialGradient<sup>12+</sup> 7871 7872static createRadialGradient(centerPt: common2D.Point, radius: number, colors: Array\<number>, mode: TileMode, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect; 7873 7874Creates a **ShaderEffect** object that generates a radial gradient based on the center and radius of a circle. The radial gradient transitions colors from the center to the ending shape in a radial manner. 7875 7876**System capability**: SystemCapability.Graphics.Drawing 7877 7878**Parameters** 7879 7880| Name| Type | Mandatory| Description | 7881| ------ | -------------------------------------------------- | ---- | -------------- | 7882| centerPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Center of the circle.| 7883| radius | number | Yes | Radius of the gradient. A negative number is invalid. The value is a floating point number.| 7884| colors | Array\<number> | Yes | Array of colors to distribute between the center and ending shape of the circle. The values in the array are 32-bit (ARGB) unsigned integers.| 7885| mode | [TileMode](#tilemode12) | Yes | Tile mode of the shader effect.| 7886| pos | Array\<number> \| null | No | Relative position of each color in the color array. The array length must be the same as that of **colors**. The first element in the array must be 0.0, the last element must be 1.0, and the middle elements must be between 0.0 and 1.0 and increase by index. The default value is null, indicating that colors are evenly distributed between the center and ending shape of the circle.| 7887| matrix | [Matrix](#matrix12) \| null | No | **Matrix** object used to perform matrix transformation on the shader effect. The default value is null, indicating the identity matrix.| 7888 7889 7890 7891The preceding figure shows the display effect when the **colors** array is set to red, green, and blue and the **pos** array is set to 0.0, 0.75, and 1.0. The triangle subscript is the relative position of the color between the center and ending shape of the circle. Gradient colors are used between them. 7892 7893**Return value** 7894 7895| Type | Description | 7896| ------- | ------------------------- | 7897| [ShaderEffect](#shadereffect12) | **ShaderEffect** object created.| 7898 7899**Error codes** 7900 7901For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7902 7903| ID| Error Message| 7904| ------- | --------------------------------------------| 7905| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 7906 7907**Example** 7908 7909```ts 7910import { common2D,drawing } from '@kit.ArkGraphics2D'; 7911 7912let centerPt: common2D.Point = { x: 100, y: 100 }; 7913let shaderEffect = drawing.ShaderEffect.createRadialGradient(centerPt, 100, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 7914``` 7915 7916### createSweepGradient<sup>12+</sup> 7917 7918static createSweepGradient(centerPt: common2D.Point, colors: Array\<number>, 7919 mode: TileMode, startAngle: number, endAngle: number, pos?: Array\<number> | null, 7920 matrix?: Matrix | null): ShaderEffect; 7921 7922Creates a **ShaderEffect** object that generates a sweep gradient based on the center. A sweep gradient paints a gradient of colors in a clockwise or counterclockwise direction based on a given circle center. 7923 7924**System capability**: SystemCapability.Graphics.Drawing 7925 7926**Parameters** 7927 7928| Name| Type | Mandatory| Description | 7929| ------ | -------------------------------------------------- | ---- | -------------- | 7930| centerPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Center of the circle.| 7931| colors | Array\<number> | Yes | Array of colors to distribute between the start angle and end angle. The values in the array are 32-bit (ARGB) unsigned integers.| 7932| mode | [TileMode](#tilemode12) | Yes | Tile mode of the shader effect.| 7933| startAngle | number | Yes | Start angle of the sweep gradient, in degrees. The value 0 indicates the positive direction of the X axis. A positive number indicates an offset towards the positive direction, and a negative number indicates an offset towards the negative direction. The value is a floating point number.| 7934| endAngle | number | Yes | End angle of the sweep gradient, in degrees. The value 0 indicates the positive direction of the X axis. A positive number indicates an offset towards the positive direction, and a negative number indicates an offset towards the negative direction. A value less than the start angle is invalid. The value is a floating point number.| 7935| pos | Array\<number> \| null | No | Relative position of each color in the color array. The array length must be the same as that of **colors**. The first element in the array must be 0.0, the last element must be 1.0, and the middle elements must be between 0.0 and 1.0 and increase by index. The default value is null, indicating that the colors are evenly distributed between the start angle and end angle.| 7936| matrix | [Matrix](#matrix12) \| null | No |**Matrix** object used to perform matrix transformation on the shader effect. The default value is null, indicating the identity matrix.| 7937 7938 7939 7940The preceding figure shows the display effect when the **colors** array is set to red, green, and blue, the **pos** array is set to 0.0, 0.75, and 1.0, **startAngle** is set to 0 degrees, and **endAngle** is set to 180 degrees. In the figure, **0.0** corresponds to the position of 0 degrees, **0.75** corresponds to the position of 135 degrees, and **1.0** corresponds to the position of 180 degrees. Gradient colors are used between them. 7941 7942**Return value** 7943 7944| Type | Description | 7945| ------- | ------------------------- | 7946| [ShaderEffect](#shadereffect12) | **ShaderEffect** object created.| 7947 7948**Error codes** 7949 7950For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 7951 7952| ID| Error Message| 7953| ------- | --------------------------------------------| 7954| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 7955 7956**Example** 7957 7958```ts 7959import { common2D,drawing } from '@kit.ArkGraphics2D'; 7960 7961let centerPt: common2D.Point = { x: 100, y: 100 }; 7962let shaderEffect = drawing.ShaderEffect.createSweepGradient(centerPt, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT, 100, 200); 7963``` 7964 7965### createConicalGradient<sup>12+</sup> 7966 7967static createConicalGradient(startPt: common2D.Point, startRadius: number, endPt: common2D.Point, endRadius: number, colors: Array\<number>, mode: TileMode, 7968pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect; 7969 7970Creates a **ShaderEffect** object that generates a conical gradient between two given circles. 7971 7972**System capability**: SystemCapability.Graphics.Drawing 7973 7974**Parameters** 7975 7976| Name| Type | Mandatory| Description | 7977| ------ | -------------------------------------------------- | ---- | -------------- | 7978| startPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes |Center of the start circle of the gradient.| 7979| startRadius | number | Yes | Radius of the start circle of the gradient. A negative number is invalid. The value is a floating point number.| 7980| endPt | [common2D.Point](js-apis-graphics-common2D.md#point) | Yes | Center of the end circle of the gradient.| 7981| endRadius | number | Yes | Radius of the end circle of the gradient. A negative value is invalid. The value is a floating point number.| 7982| colors | Array\<number> | Yes | Array of colors to distribute between the start circle and end circle. The values in the array are 32-bit (ARGB) unsigned integers.| 7983| mode | [TileMode](#tilemode12) | Yes | Tile mode of the shader effect.| 7984| pos | Array\<number> \| null | No | Relative position of each color in the color array. The array length must be the same as that of **colors**. The first element in the array must be 0.0, the last element must be 1.0, and the middle elements must be between 0.0 and 1.0 and increase by index. The default value is null, indicating that colors are evenly distributed between the two circles.| 7985| matrix | [Matrix](#matrix12) \| null | No | **Matrix** object used to perform matrix transformation on the shader effect. The default value is null, indicating the identity matrix.| 7986 7987 7988 7989The preceding figure shows the display effect when the **colors** array is set to red, green, and blue and the **pos** array is set to 0.0, 0.5, and 1.0. The left part shows the drawing result when the start circle is not in the end circle, and the right part shows the drawing result when the start circle is in the end circle. 7990 7991**Return value** 7992 7993| Type | Description | 7994| ------- | ------------------------- | 7995| [ShaderEffect](#shadereffect12) | **ShaderEffect** object created.| 7996 7997**Error codes** 7998 7999For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 8000 8001| ID| Error Message| 8002| ------- | --------------------------------------------| 8003| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 8004 8005**Example** 8006 8007```ts 8008import { common2D,drawing } from '@kit.ArkGraphics2D'; 8009 8010let startPt: common2D.Point = { x: 100, y: 100 }; 8011let endPt: common2D.Point = {x: 200, y: 200}; 8012let shaderEffect = drawing.ShaderEffect.createConicalGradient(startPt, 100, endPt, 50, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 8013``` 8014 8015## RegionOp<sup>12+</sup> 8016 8017Enumerates the operations for combining two regions. 8018 8019**System capability**: SystemCapability.Graphics.Drawing 8020 8021| Name | Value | Description | Diagram | 8022| --------------------- | ---- | ------------------------------ | -------- | 8023| DIFFERENCE | 0 | Difference operation. | | 8024| INTERSECT | 1 | Intersect operation.| | 8025| UNION | 2 | Union operation. | | 8026| XOR | 3 | XOR operation. | | 8027| REVERSE_DIFFERENCE | 4 | Reverse difference operation. | | 8028| REPLACE | 5 | Replace operation. | | 8029 8030> **NOTE** 8031> 8032> The schematic diagram shows the result obtained by combining a red region with a blue region at different operation mode. The green region is the region obtained. 8033 8034## CornerPos<sup>12+</sup> 8035 8036Enumerates the corner positions of a rounded rectangle. 8037 8038**System capability**: SystemCapability.Graphics.Drawing 8039 8040| Name | Value | Description | 8041| --------------------- | ---- | ------------------------------ | 8042| TOP_LEFT_POS | 0 | Top left corner of the rounded rectangle. | 8043| TOP_RIGHT_POS | 1 | Top right corner of the rounded rectangle.| 8044| BOTTOM_RIGHT_POS | 2 | Bottom right corner of the rounded rectangle. | 8045| BOTTOM_LEFT_POS | 3 | Bottom left corner of the rounded rectangle. | 8046
