1# Shape Clipping
2
3Shape clipping changes the visible portion of a component through clipping or masking.
4
5>  **NOTE**
6>
7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
8
9## clip<sup>12+</sup>
10
11clip(value: boolean)
12
13Sets whether to clip the areas of child components that extend beyond this component's boundaries, that is, whether to perform clipping based on the edge contour of the parent container
14
15**System capability**: SystemCapability.ArkUI.ArkUI.Full
16
17**Widget capability**: This API can be used in ArkTS widgets since API version 12.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**Parameters**
22
23| Name| Type                                                        | Mandatory| Description                                                        |
24| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
25| value  | boolean | Yes  | Whether to perform clipping based on the edge contour of the parent container.<br>Default value: **false**|
26
27## clip<sup>(deprecated)</sup>
28
29clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute)
30
31Sets whether to clip this component based on the given shape.
32
33> **NOTE**
34>
35> This API is supported since API version 7 and deprecated since API version 12. You are advised to use [clip](#clip12) and [clipShape](#clipshape12) instead.
36
37**Widget capability**: This API can be used in ArkTS widgets since API version 9.
38
39**System capability**: SystemCapability.ArkUI.ArkUI.Full
40
41**Parameters**
42
43| Name| Type                                                        | Mandatory| Description                                                        |
44| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
45| value  | boolean \| [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) | Yes  | Clip mode. If the value is a shape, the component is clipped based on the specified shape. If the value is of the Boolean type, it specifies whether to clip the component based on the edge contour of the parent container.<br>Default value: **false**|
46
47## clipShape<sup>12+</sup>
48
49clipShape(value: CircleShape | EllipseShape | PathShape | RectShape)
50
51Clips this component based on the given shape.
52
53**System capability**: SystemCapability.ArkUI.ArkUI.Full
54
55**Widget capability**: This API can be used in ArkTS widgets since API version 12.
56
57**Atomic service API**: This API can be used in atomic services since API version 12.
58
59**Parameters**
60
61| Name| Type                                                        | Mandatory| Description                                                        |
62| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
63| value  | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | Yes  | Shape that the component to be clipped into.|
64
65## mask<sup>12+</sup>
66
67mask(value: ProgressMask)
68
69Adds a mask of the specified shape to the component.
70
71**System capability**: SystemCapability.ArkUI.ArkUI.Full
72
73**Atomic service API**: This API can be used in atomic services since API version 12.
74
75**Parameters**
76
77| Name| Type                                                        | Mandatory| Description                            |
78| ------ | ------------------------------------------------------------ | ---- | -------------------------------- |
79| value  | [ProgressMask](#progressmask10) | Yes  | Mask to add to the component, which allows for dynamic adjustment of progress, maximum value, and color settings.|
80
81## mask<sup>(deprecated)</sup>
82
83mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask)
84
85Adds a mask of the specified shape to the component.
86
87> **NOTE**
88>
89> This API is supported since API version 7 and deprecated since API version 12. You are advised to use [mask](#mask12) and [maskShape](#maskshape12) instead.
90
91**Widget capability**: This API can be used in ArkTS widgets since API version 9.
92
93**System capability**: SystemCapability.ArkUI.ArkUI.Full
94
95**Parameters**
96
97| Name| Type                                                        | Mandatory| Description                            |
98| ------ | ------------------------------------------------------------ | ---- | -------------------------------- |
99| value  | [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) \| [ProgressMask](#progressmask10)<sup>10+</sup> | Yes  | Mask of the specified shape to add to the component.|
100
101## maskShape<sup>12+</sup>
102
103maskShape(value: CircleShape | EllipseShape | PathShape | RectShape)
104
105Adds a mask of the specified shape to the component.
106
107**System capability**: SystemCapability.ArkUI.ArkUI.Full
108
109**Widget capability**: This API can be used in ArkTS widgets since API version 12.
110
111**Atomic service API**: This API can be used in atomic services since API version 12.
112
113**Parameters**
114
115| Name| Type                                                        | Mandatory| Description                            |
116| ------ | ------------------------------------------------------------ | ---- | -------------------------------- |
117| value  | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | Yes  | Mask of the specified shape to add to the component.|
118
119## ProgressMask<sup>10+</sup>
120
121Implements a **ProgressMask** object to set the progress, maximum value, and color of the mask.
122
123**Atomic service API**: This API can be used in atomic services since API version 11.
124
125**System capability**: SystemCapability.ArkUI.ArkUI.Full
126
127### constructor<sup>10+</sup>
128
129constructor(value: number, total: number, color: ResourceColor)
130
131Constructs a **ProgressMask** object.
132
133**Atomic service API**: This API can be used in atomic services since API version 11.
134
135**System capability**: SystemCapability.ArkUI.ArkUI.Full
136
137**Parameters**
138
139| Name| Type                                  | Mandatory| Description          |
140| ------ | ------------------------------------------ | ---- | ------------------ |
141| value  | number                                     | Yes  | Current value of the progress mask.|
142| total  | number                                     | Yes  | Maximum value of the progress mask.|
143| color  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the progress mask.  |
144
145### updateProgress<sup>10+</sup>
146
147updateProgress(value: number): void
148
149Updates the progress value of the progress mask.
150
151**Atomic service API**: This API can be used in atomic services since API version 11.
152
153**System capability**: SystemCapability.ArkUI.ArkUI.Full
154
155**Parameters**
156
157| Name| Type| Mandatory| Description          |
158| ------ | -------- | ---- | ------------------ |
159| value  | number   | Yes  | Current value of the progress mask.|
160
161### updateColor<sup>10+</sup>
162
163updateColor(value: ResourceColor): void
164
165Updates the color of the progress mask.
166
167**Atomic service API**: This API can be used in atomic services since API version 11.
168
169**System capability**: SystemCapability.ArkUI.ArkUI.Full
170
171**Parameters**
172
173| Name| Type                                  | Mandatory| Description        |
174| ------ | ------------------------------------------ | ---- | ---------------- |
175| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the progress mask.|
176
177### enableBreathingAnimation<sup>12+</sup>
178
179enableBreathingAnimation(value: boolean): void
180
181Sets whether to enable the breathing animation when the progress indicator is full. By default, the breathing animation is disabled.
182
183**Atomic service API**: This API can be used in atomic services since API version 12.
184
185**System capability**: SystemCapability.ArkUI.ArkUI.Full
186
187**Parameters**
188
189| Name| Type                                  | Mandatory| Description        |
190| ------ | ------------------------------------------ | ---- | ---------------- |
191| value  | boolean | Yes  | Whether to enable the breathing animation. The value **true** means to enable the breathing animation, and **false** means the opposite. Default value: **false**|
192
193
194## Example
195
196### Example 1
197
198```ts
199// xxx.ets
200@Entry
201@Component
202struct ClipAndMaskExample {
203  build() {
204    Column({ space: 15 }) {
205      Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC')
206      Row() {
207        Image($r('app.media.testImg')).width('500px').height('280px')
208      }
209      .clip(true) // If clip is not set to true, the image is not confined by the rounded corners of the <Row> component and may extend beyond the <Row> component.
210      .borderRadius(20)
211      // Clip the image based on a circle with a diameter of 280 px.
212      Image($r('app.media.testImg'))
213        .clipShape(new Circle({ width: '280px', height: '280px' }))
214        .width('500px').height('280px')
215
216      Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC')
217      // Add a 500 px x 280 px square mask to the image.
218      Image($r('app.media.testImg'))
219        .maskShape(new Rect({ width: '500px', height: '280px' }).fill(Color.Gray))
220        .width('500px').height('280px')
221
222      // Add a 280 px x 280 px circular mask to the image.
223      Image($r('app.media.testImg'))
224        .maskShape(new Circle({ width: '280px', height: '280px' }).fill(Color.Gray))
225        .width('500px').height('280px')
226    }
227    .width('100%')
228    .margin({ top: 15 })
229  }
230}
231```
232
233![clipAndMask](figures/clipAndMask.PNG)
234
235### Example 2
236
237```ts
238@Entry
239@Component
240struct ProgressMaskExample {
241  @State progressflag1: boolean = true;
242  @State color: Color = 0x01006CDE;
243  @State value: number = 10.0;
244  @State enableBreathingAnimation: boolean = false;
245  @State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray);
246  build() {
247    Column({ space: 15 }) {
248      Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC')
249      // Add a 280px x 280px progress mask to the image.
250      Image($r('app.media.testImg'))
251        .width('500px').height('280px')
252        .mask(this.progress)
253        .animation({
254          duration: 2000, // Animation duration.
255          .curve(Curve.Linear) // Animation curve.
256          delay: 0, // Animation delay.
257          iterations: 1, // Number of playback times.
258          playMode: PlayMode.Normal // Animation playback mode.
259        }) // Animation configuration for the width and height attributes of the <Button> component.
260
261      // Update the progress value of the progress mask.
262      Button('updateProgress')
263        .onClick((event?: ClickEvent) => {
264          this.value += 10;
265          this.progress.updateProgress(this.value);
266        }).width(200).height(50).margin(20)
267
268      // Update the color of the progress mask.
269      Button('updateColor')
270        .onClick((event?: ClickEvent) => {
271          if (this.progressflag1) {
272            this.progress.updateColor(0x9fff0000);
273          } else {
274            this.progress.updateColor(0x9f0000ff);
275          }
276          this.progressflag1 = !this.progressflag1
277        }).width(200).height(50).margin(20)
278
279      // Enable or disable the breathing animation.
280      Button('enableBreathingAnimation:' + this.enableBreathingAnimation)
281        .onClick((event?: ClickEvent) => {
282          this.enableBreathingAnimation = !this.enableBreathingAnimation
283          this.progress.enableBreathingAnimation(this.enableBreathingAnimation);
284        }).width(200).height(50).margin(20)
285
286      // Restore the progress mask.
287      Button('click reset!')
288        .onClick((event?: ClickEvent) => {
289          this.value = 0;
290          this.progress.updateProgress(this.value);
291        }).width(200).height(50).margin(20)
292    }
293    .width('100%')
294    .margin({ top: 15 })
295  }
296}
297```
298
299![progressMask](figures/progressMask.gif)
300