1# Theme Framework Subsystem – Wallpaper Management Service Changelog
2
3
4## cl.wallpaper.1 Permission Change of getColorsSync, getMinHeightSync, getMinWidthSync, restore, and setImage
5Changed the **getColorsSync**, **getMinHeightSync**, **getMinWidthSync**, restore, and **setImage** APIs to system APIs since API version 9.
6
7You need to adapt your application based on the following information.
8
9**Change Impact**
10
11The JS API needs to be adapted for applications developed based on earlier versions. Otherwise, relevant functions will be affected.
12
13- Involved APIs:
14
15```js
16    function getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>;
17    function getMinHeightSync(): number;
18    function getMinWidthSync(): number;
19    function restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
20    function restore(wallpaperType: WallpaperType): Promise<void>;
21    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
22    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>;
23```
24
25- Before change:
26
27```js
28    /**
29     * Obtains the wallpaper colors for the wallpaper of the specified type. Returns rgbaColor type of array callback function.
30     * @param wallpaperType Indicates the wallpaper type.
31     * @returns { Array<RgbaColor> } the Array<RgbaColor> returned by the function.
32     * @throws {BusinessError} 401 - parameter error.
33     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
34     * @syscap SystemCapability.MiscServices.Wallpaper
35     * @systemapi Hide this for inner system use.
36     * @since 9
37     */
38    function getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>;
39
40    /**
41     * Obtains the minimum height of the wallpaper. in pixels. returns 0 if no wallpaper has been set.
42     * @returns { number } the number returned by the function.
43     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
44     * @syscap SystemCapability.MiscServices.Wallpaper
45     * @systemapi Hide this for inner system use.
46     * @since 9
47     */
48    function getMinHeightSync(): number;
49
50    /**
51     * Obtains the minimum width of the wallpaper. in pixels. returns 0 if no wallpaper has been set.
52     * @returns { number } the number returned by the function.
53     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
54     * @syscap SystemCapability.MiscServices.Wallpaper
55     * @systemapi Hide this for inner system use.
56     * @since 9
57     */
58    function getMinWidthSync(): number;
59
60    /**
61     * Removes a wallpaper of the specified type and restores the default one.
62     * @param wallpaperType Indicates the wallpaper type.
63     * @throws {BusinessError} 401 - parameter error.
64     * @throws {BusinessError} 201 - permission denied.
65     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
66     * @permission ohos.permission.SET_WALLPAPER
67     * @syscap SystemCapability.MiscServices.Wallpaper
68     * @systemapi Hide this for inner system use.
69     * @since 9
70     */
71    function restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
72
73    /**
74     * Removes a wallpaper of the specified type and restores the default one.
75     * @param wallpaperType Indicates the wallpaper type.
76     * @throws {BusinessError} 401 - parameter error.
77     * @throws {BusinessError} 201 - permission denied.
78     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
79     * @permission ohos.permission.SET_WALLPAPER
80     * @syscap SystemCapability.MiscServices.Wallpaper
81     * @systemapi Hide this for inner system use.
82     * @since 9
83     */
84    function restore(wallpaperType: WallpaperType): Promise<void>;
85
86    /**
87     * Sets a wallpaper of the specified type based on the uri path from a JPEG or PNG file or the pixel map of a PNG file.
88     * @param source Indicates the uri path from a JPEG or PNG file or the pixel map of the PNG file.
89     * @param wallpaperType Indicates the wallpaper type.
90     * @throws {BusinessError} 401 - parameter error.
91     * @throws {BusinessError} 201 - permission denied.
92     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
93     * @permission ohos.permission.SET_WALLPAPER
94     * @syscap SystemCapability.MiscServices.Wallpaper
95     * @systemapi Hide this for inner system use.
96     * @since 9
97     */
98    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
99
100    /**
101     * Sets a wallpaper of the specified type based on the uri path from a JPEG or PNG file or the pixel map of a PNG file.
102     * @param source Indicates the uri path from a JPEG or PNG file or the pixel map of the PNG file.
103     * @param wallpaperType Indicates the wallpaper type.
104     * @throws {BusinessError} 401 - parameter error.
105     * @throws {BusinessError} 201 - permission denied.
106     * @throws {BusinessError} 202 - permission verification failed, application which is not a system application uses system API.
107     * @permission ohos.permission.SET_WALLPAPER
108     * @syscap SystemCapability.MiscServices.Wallpaper
109     * @systemapi Hide this for inner system use.
110     * @since 9
111     */
112    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>;
113```
114
115- After change:
116
117```js
118    /**
119     * Obtains the wallpaper colors for the wallpaper of the specified type. Returns rgbaColor type of array callback function.
120     * @param wallpaperType Indicates the wallpaper type.
121     * @returns { Array<RgbaColor> } the Array<RgbaColor> returned by the function.
122     * @throws {BusinessError} 401 - parameter error.
123     * @syscap SystemCapability.MiscServices.Wallpaper
124     * @since 9
125     */
126    function getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>;
127
128    /**
129     * Obtains the minimum height of the wallpaper. in pixels. returns 0 if no wallpaper has been set.
130     * @returns { number } the number returned by the function.
131     * @syscap SystemCapability.MiscServices.Wallpaper
132     * @since 9
133     */
134    function getMinHeightSync(): number;
135
136    /**
137     * Obtains the minimum width of the wallpaper. in pixels. returns 0 if no wallpaper has been set.
138     * @returns { number } the number returned by the function.
139     * @syscap SystemCapability.MiscServices.Wallpaper
140     * @since 9
141     */
142    function getMinWidthSync(): number;
143
144    /**
145     * Removes a wallpaper of the specified type and restores the default one.
146     * @param wallpaperType Indicates the wallpaper type.
147     * @throws {BusinessError} 401 - parameter error.
148     * @throws {BusinessError} 201 - permission denied.
149     * @permission ohos.permission.SET_WALLPAPER
150     * @syscap SystemCapability.MiscServices.Wallpaper
151     * @since 9
152     */
153    function restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
154
155    /**
156     * Removes a wallpaper of the specified type and restores the default one.
157     * @param wallpaperType Indicates the wallpaper type.
158     * @throws {BusinessError} 401 - parameter error.
159     * @throws {BusinessError} 201 - permission denied.
160     * @permission ohos.permission.SET_WALLPAPER
161     * @syscap SystemCapability.MiscServices.Wallpaper
162     * @since 9
163     */
164    function restore(wallpaperType: WallpaperType): Promise<void>;
165
166    /**
167     * Sets a wallpaper of the specified type based on the uri path from a JPEG or PNG file or the pixel map of a PNG file.
168     * @param source Indicates the uri path from a JPEG or PNG file or the pixel map of the PNG file.
169     * @param wallpaperType Indicates the wallpaper type.
170     * @throws {BusinessError} 401 - parameter error.
171     * @throws {BusinessError} 201 - permission denied.
172     * @permission ohos.permission.SET_WALLPAPER
173     * @syscap SystemCapability.MiscServices.Wallpaper
174     * @since 9
175     */
176    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
177
178    /**
179     * Sets a wallpaper of the specified type based on the uri path from a JPEG or PNG file or the pixel map of a PNG file.
180     * @param source Indicates the uri path from a JPEG or PNG file or the pixel map of the PNG file.
181     * @param wallpaperType Indicates the wallpaper type.
182     * @throws {BusinessError} 401 - parameter error.
183     * @throws {BusinessError} 201 - permission denied.
184     * @permission ohos.permission.SET_WALLPAPER
185     * @syscap SystemCapability.MiscServices.Wallpaper
186     * @since 9
187     */
188    function setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>;
189```
190
191
192**Adaptation Guide**
193
194Make sure the APIs are only invoked by system applications.
195
196The code snippet is as follows:
197
198```js
199    try {
200        let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
201        console.log(`success to getColorsSync: ${JSON.stringify(colors)}`);
202    } catch (error) {
203        console.error(`failed to getColorsSync because: ${JSON.stringify(error)}`);
204    }
205```
206
207```js
208    let minHeight = wallpaper.getMinHeightSync();
209```
210
211```js
212    let minWidth = wallpaper.getMinWidthSync();
213```
214
215```js
216    wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
217        if (error) {
218            console.error(`failed to restore because: ${JSON.stringify(error)}`);
219            return;
220        }
221        console.log(`success to restore.`);
222    });
223```
224
225```js
226    wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
227        console.log(`success to restore.`);
228      }).catch((error) => {
229        console.error(`failed to restore because: ${JSON.stringify(error)}`);
230    });
231```
232
233```js
234    // The source type is string.
235    let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
236    wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
237        if (error) {
238            console.error(`failed to setImage because: ${JSON.stringify(error)}`);
239            return;
240        }
241        console.log(`success to setImage.`);
242    });
243```
244
245```js
246    // The source type is string.
247    let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
248    wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
249        console.log(`success to setImage.`);
250    }).catch((error) => {
251        console.error(`failed to setImage because: ${JSON.stringify(error)}`);
252    });
253```
254
255
256## cl.wallpaper.2 Deprecation of getIdSync, getFileSync, isChangeAllowed, isUserChangeAllowed, on, off, and RgbaColor
257Deprecated the **getIdSync**, **getFileSync**, **isChangeAllowed**, **isUserChangeAllowed**, **on**, **off**, and **RgbaColor** APIs since API version 9.
258
259You need to adapt your application based on the following information.
260
261**Change Impact**
262
263The APIs can no longer be used after being deleted.
264
265- Involved APIs:
266
267```js
268    function getIdSync(wallpaperType: WallpaperType): number;
269    function getFileSync(wallpaperType: WallpaperType): number;
270    function isChangeAllowed(): boolean;
271    function isUserChangeAllowed(): boolean;
272    function on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void;
273    function off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void;
274    interface RgbaColor {
275        red: number;
276        green: number;
277        blue: number;
278        alpha: number;
279        }
280```
281
282- Before change:
283
284```js
285    function getIdSync(wallpaperType: WallpaperType): number;
286    function getFileSync(wallpaperType: WallpaperType): number;
287    function isChangeAllowed(): boolean;
288    function isUserChangeAllowed(): boolean;
289    function on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void;
290    function off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void;
291    interface RgbaColor {
292        red: number;
293        green: number;
294        blue: number;
295        alpha: number;
296        }
297```
298
299- After change:
300
301  The APIs are deleted.
302
303
304**Adaptation Guide**
305
306Update the code so that the deprecated APIs are not used.
307