• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# DrawingRenderingContext
2
3**DrawingRenderingContext** provides a rendering context for drawing rectangles, text, images, and other objects on a canvas.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
8
9## APIs
10
11DrawingRenderingContext(unit?: LengthMetricsUnit)
12
13**Widget capability**: This API can be used in ArkTS widgets since API version 12.
14
15**System capability**: SystemCapability.ArkUI.ArkUI.Full
16
17**Parameters**
18
19| Name     | Type| Mandatory  | Description|
20| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
21| unit<sup>12+</sup>  | [LengthMetricsUnit](../js-apis-arkui-graphics.md#lengthmetricsunit12) | No   | Unit mode of the **DrawingRenderingContext** object. The value cannot be changed once set. The configuration method is the same as that of [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12).<br>Default value: **DEFAULT**.|
22
23## Attributes
24
25**Atomic service API**: This API can be used in atomic services since API version 12.
26
27**System capability**: SystemCapability.ArkUI.ArkUI.Full
28
29| Name      | Type| Read Only| Optional| Description|
30| ---------- | ------------ | -------------------- | ---------------------------- | ---------------------------- |
31| size       | [Size](#size)    | No| No| Width and height of the context.<br>Default unit: vp                                           |
32| canvas     | [Canvas](../../apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md) | No| No| **Canvas** object. For details, see [Canvas](../../apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md).|
33
34### Size
35
36**Atomic service API**: This API can be used in atomic services since API version 12.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40| Name| Type| Read Only| Optional| Description|
41| ---------- | -------------- | ------ | ---------------- | ------------------------ |
42| width | number | No| No| Width of the **DrawingRenderingContext** object, which corresponds to the width of the associated **Canvas** component.|
43| height | number | No| No| Height of the **DrawingRenderingContext** object, which corresponds to the height of the associated **Canvas** component.|
44
45## Methods
46
47### invalidate
48
49invalidate(): void
50
51**Atomic service API**: This API can be used in atomic services since API version 12.
52
53**System capability**: SystemCapability.ArkUI.ArkUI.Full
54
55Invalidates the component and triggers re-rendering of the component.
56
57## DrawingCanvas<sup>12+</sup>
58
59type DrawingCanvas = Canvas
60
61Defines a canvas object for drawing content on the **XComponent** component.
62
63**Atomic service API**: This API can be used in atomic services since API version 12.
64
65**System capability**: SystemCapability.ArkUI.ArkUI.Full
66
67| Type                 | Description          |
68| --------------------- | -------------- |
69| [Canvas](../../apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md) | Canvas object.|
70
71## Example
72
73This example shows how to use the APIs in **DrawingRenderingContext** for drawing.
74
75```ts
76import { common2D, drawing } from '@kit.ArkGraphics2D';
77
78// xxx.ets
79@Entry
80@Component
81struct CanvasExample {
82  private context: DrawingRenderingContext = new DrawingRenderingContext();
83
84  build() {
85    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
86      Canvas(this.context)
87        .width('100%')
88        .height('50%')
89        .backgroundColor('#D5D5D5')
90        .onReady(() => {
91          let brush = new drawing.Brush();
92          // Draw a circle with center at (200, 200) and radius of 100, filled with RGBA(39, 135, 217, 255).
93          brush.setColor({
94            alpha: 255,
95            red: 39,
96            green: 135,
97            blue: 217
98          });
99          this.context.canvas.attachBrush(brush);
100          this.context.canvas.drawCircle(200, 200, 100);
101          this.context.canvas.detachBrush();
102          this.context.invalidate();
103        })
104      Button("Clear")
105        .width('120')
106        .height('50')
107        .onClick(() => {
108          let color: common2D.Color = {
109            alpha: 0,
110            red: 0,
111            green: 0,
112            blue: 0
113          };
114          // Clear the canvas using RGBA(0, 0, 0, 0).
115          this.context.canvas.clear(color);
116          this.context.invalidate();
117        })
118    }
119    .width('100%')
120    .height('100%')
121  }
122}
123```
124
125Figure 1 Circle with center at (200, 200) and radius of 100, filled with RGBA(39, 135, 217, 255)
126
127  ![canvas_drawingRenderingContext](figures/canvas_drawingRenderingContext.png)
128
129Figure 2 Clearing the canvas with the Clear button
130
131  ![canvas_drawingRenderingContextClear](figures/canvas_drawingRenderingContextClear.png)
132<!--no_check-->