1# @ohos.arkui.drawableDescriptor (DrawableDescriptor)
2
3The **DrawableDescriptor** module provides APIs for obtaining **pixelMap** objects, including the foreground, background, mask, and layered icons.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> You can preview how this component looks on a real device, but not in DevEco Studio Previewer.
10
11## Modules to Import
12
13```ts
14import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
15```
16
17## DrawableDescriptor
18
19Resources in PNG, JPG, BMP, SVG, GIF, WEBP, ASTC, and SUT formats are supported.
20
21### getPixelMap
22
23getPixelMap(): image.PixelMap
24
25Obtains this **pixelMap** object.
26
27**Atomic service API**: This API can be used in atomic services since API version 11.
28
29**System capability**: SystemCapability.ArkUI.ArkUI.Full
30
31**Return value**
32
33| Type                                      | Description      |
34| ---------------------------------------- | -------- |
35| [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | **PixelMap** object.|
36
37**Example**
38  ```ts
39import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
40let resManager = getContext().resourceManager
41let pixmap: DrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.icon')
42    .id)) as DrawableDescriptor;
43let pixmapNew: object = pixmap.getPixelMap()
44  ```
45
46Creates a **DrawableDescriptor** object when the passed resource ID or name belongs to a common image.
47
48## PixelMapDrawableDescriptor<sup>12+</sup>
49
50Implements a **PixelMapDrawableDescriptor** object , which can be created by passing in a **pixelMap** object. Inherits from [DrawableDescriptor](#drawabledescriptor).
51
52### constructor<sup>12+</sup>
53
54constructor(src?: image.PixelMap)
55
56A constructor used to create a **PixelMapDrawableDescriptor** object.
57
58**Atomic service API**: This API can be used in atomic services since API version 12.
59
60**System capability**: SystemCapability.ArkUI.ArkUI.Full
61
62**Parameters**
63
64| Name    | Type             | Mandatory | Description                                      |
65| --------- | ---------------- | ---- | ------------------------------------------ |
66| src | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)  | No| **PixelMap** image data.|
67
68
69## LayeredDrawableDescriptor
70
71Creates a **LayeredDrawableDescriptor** object when the passed resource ID or name belongs to a JSON file that contains foreground and background resources. Inherits from [DrawableDescriptor](#drawabledescriptor).
72
73The **drawable.json** file is located under **entry/src/main/resources/base/media** in the project directory. Below shows the file content:
74
75```json
76{
77  "layered-image":
78  {
79    "background" : "$media:background",
80    "foreground" : "$media:foreground"
81  }
82}
83```
84
85**Example**
86
871. Create a **LayeredDrawableDescriptor** object from a JSON file.
88
89    ```ts
90    // xxx.ets
91    import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
92
93    @Entry
94    @Component
95    struct Index {
96      private resManager = getContext().resourceManager
97
98      build() {
99        Row() {
100          Column() {
101            Image((this.resManager.getDrawableDescriptor($r('app.media.drawable').id) as LayeredDrawableDescriptor))
102            Image(((this.resManager.getDrawableDescriptor($r('app.media.drawable')
103            .id) as LayeredDrawableDescriptor).getForeground()).getPixelMap())
104          }.height('50%')
105        }.width('50%')
106      }
107    }
108    ```
1092. Creates a **LayeredDrawableDescriptor** object using **PixelMapDrawableDescriptor**.
110
111    ```ts
112    import { DrawableDescriptor, LayeredDrawableDescriptor, PixelMapDrawableDescriptor } from '@kit.ArkUI'
113    import { image } from '@kit.ImageKit'
114
115    @Entry
116    @Component
117    struct Index {
118      @State fore1: image.PixelMap | undefined = undefined
119      @State back1: image.PixelMap | undefined = undefined
120
121      @State foregroundDraw:DrawableDescriptor|undefined=undefined
122      @State backgroundDraw:DrawableDescriptor|undefined=undefined
123      @State maskDraw:DrawableDescriptor|undefined=undefined
124      @State maskPixel: image.PixelMap | undefined = undefined
125      @State draw : LayeredDrawableDescriptor | undefined = undefined
126      async aboutToAppear() {
127        this.fore1 = await this.getPixmapFromMedia($r('app.media.foreground'))
128        this.back1 = await this.getPixmapFromMedia($r('app.media.background'))
129        this.maskPixel = await this.getPixmapFromMedia($r('app.media.ohos_icon_mask'))
130        // Create a LayeredDrawableDescriptor object using PixelMapDrawableDescriptor.
131        this.foregroundDraw = new PixelMapDrawableDescriptor(this.fore1)
132        this.backgroundDraw = new PixelMapDrawableDescriptor(this.back1)
133        this.maskDraw = new PixelMapDrawableDescriptor(this.maskPixel)
134
135        this.draw = new LayeredDrawableDescriptor(this.foregroundDraw,this.backgroundDraw,this.maskDraw)
136      }
137      build() {
138        Row() {
139          Column() {
140              Image(this.draw)
141                .width(300)
142                .height(300)
143          }.height('100%').justifyContent(FlexAlign.Center)
144        }.width('100%').height("100%").backgroundColor(Color.Pink)
145      }
146      // Obtain pixelMap from a resource through the image framework based on the resource
147      private async getPixmapFromMedia(resource: Resource) {
148        let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
149          bundleName: resource.bundleName,
150          moduleName: resource.moduleName,
151          id: resource.id
152        })
153        let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
154        let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
155          desiredPixelFormat: image.PixelMapFormat.BGRA_8888
156        })
157        await imageSource.release()
158        return createPixelMap
159      }
160    }
161    ```
162
163### getForeground
164getForeground(): DrawableDescriptor;
165
166Obtains the **DrawableDescriptor** object of the foreground.
167
168**Atomic service API**: This API can be used in atomic services since API version 11.
169
170**System capability**: SystemCapability.ArkUI.ArkUI.Full
171
172**Return value**
173
174| Type                                      | Description                  |
175| ---------------------------------------- | -------------------- |
176| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
177
178**Example**
179  ```ts
180import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
181let resManager = getContext().resourceManager
182let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
183    .id)) as LayeredDrawableDescriptor;
184let drawableNew: object = drawable.getForeground()
185  ```
186
187### getBackground
188
189getBackground(): DrawableDescriptor;
190
191Obtains the **DrawableDescriptor** object of the background.
192
193**Atomic service API**: This API can be used in atomic services since API version 11.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Full
196
197**Return value**
198
199| Type                                      | Description                  |
200| ---------------------------------------- | -------------------- |
201| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
202
203**Example**
204  ```ts
205import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
206let resManager = getContext().resourceManager
207let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
208    .id)) as LayeredDrawableDescriptor;
209let drawableNew: object = drawable.getBackground()
210  ```
211
212### getMask
213
214getMask(): DrawableDescriptor
215
216Obtains the **DrawableDescriptor** object of the mask.
217
218**Atomic service API**: This API can be used in atomic services since API version 11.
219
220**System capability**: SystemCapability.ArkUI.ArkUI.Full
221
222**Return value**
223
224| Type                                      | Description                  |
225| ---------------------------------------- | -------------------- |
226| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
227
228**Example**
229  ```ts
230import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
231let resManager = getContext().resourceManager
232let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
233    .id)) as LayeredDrawableDescriptor;
234let drawableNew: object = drawable.getMask()
235  ```
236### getMaskClipPath
237
238static getMaskClipPath(): string
239
240Obtains the built-in clipping path parameters of the system. It is a static method of **LayeredDrawableDescriptor**.
241
242**Atomic service API**: This API can be used in atomic services since API version 11.
243
244**System capability**: SystemCapability.ArkUI.ArkUI.Full
245
246**Return value**
247
248| Type                                      | Description                  |
249| ---------------------------------------- | -------------------- |
250| string | String of the clipping path.|
251
252**Example**
253
254  ```ts
255// xxx.ets
256import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
257
258@Entry
259@Component
260struct Index {
261  build() {
262    Row() {
263      Column() {
264        Image($r('app.media.icon'))
265          .width('200px').height('200px')
266          .clipShape(new Path({commands:LayeredDrawableDescriptor.getMaskClipPath()}))
267        Text(`Obtain the built-in clip path parameters:`)
268          .fontWeight(800)
269        Text(JSON.stringify(LayeredDrawableDescriptor.getMaskClipPath()))
270          .padding({ left: 20, right: 20 })
271      }.height('100%').justifyContent(FlexAlign.Center)
272    }.width('100%')
273  }
274}
275  ```
276
277## AnimationOptions<sup>12+</sup>
278
279Provides the playback options of the animation with a pixel map image array in an **Image** component.
280
281**Atomic service API**: This API can be used in atomic services since API version 12.
282
283**System capability**: SystemCapability.ArkUI.ArkUI.Full
284
285| Name     | Type   | Mandatory | Description                                   |
286| ---------- | ------ | -----| --------------------------------------- |
287| duration   | number | No  | Total playback duration for the pixel map image array. The default value is 1 second per image.     |
288| iterations | number | No  | Number of times that the pixel map image array is played. The default value is **1**. The value **-1** indicates that the animation is played for an unlimited number of times.|
289
290**Example**
291
292```ts
293import { AnimationOptions } from '@kit.ArkUI'
294@Entry
295@Component
296struct Example {
297  options: AnimationOptions = { duration: 2000, iterations: 1 }
298  build() {
299  }
300}
301```
302
303## AnimatedDrawableDescriptor<sup>12+</sup>
304
305Implements an **AnimatedDrawableDescriptor** object, which can be passed in when the **Image** component is used to play the pixel map image array. Inherits from [DrawableDescriptor](#drawabledescriptor).
306
307### constructor<sup>12+</sup>
308
309constructor(pixelMaps: Array\<image.PixelMap>, options?: AnimationOptions)
310
311A constructor used to create an **AnimatedDrawableDescriptor** instance.
312
313**Atomic service API**: This API can be used in atomic services since API version 12.
314
315**System capability**: SystemCapability.ArkUI.ArkUI.Full
316
317**Parameters**
318
319| Name    | Type             | Mandatory | Description                                      |
320| --------- | ---------------- | ---- | ------------------------------------------ |
321| pixelMaps | Array\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)>  | Yes  | **PixelMap** image data.|
322| options   | [AnimationOptions](#animationoptions12) | No  | Animation options.                              |
323
324**Example**
325
326```ts
327import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI'
328import { image } from '@kit.ImageKit'
329
330@Entry
331@Component
332struct Example {
333  pixelmaps: Array<image.PixelMap>  = [];
334  options: AnimationOptions = {duration:1000, iterations:-1};
335  @State animated: AnimatedDrawableDescriptor  = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
336  async aboutToAppear() {
337    this.pixelmaps.push(await this.getPixmapFromMedia($r('app.media.icon')))
338    this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
339  }
340  build() {
341    Column() {
342      Row() {
343        Image(this.animated)
344      }
345    }
346  }
347  private async getPixmapFromMedia(resource: Resource) {
348    let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
349      bundleName: resource.bundleName,
350      moduleName: resource.moduleName,
351      id: resource.id
352    })
353    let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
354    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
355      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
356    })
357    await imageSource.release()
358    return createPixelMap
359  }
360}
361
362```
363