diff --git a/en/application-dev/reference/apis/js-apis-screen-lock.md b/en/application-dev/reference/apis/js-apis-screen-lock.md index 245865cc40144c8910a4c245a9485641c0452627..c006791851e65d913d830904998ab08ebb347f0a 100644 --- a/en/application-dev/reference/apis/js-apis-screen-lock.md +++ b/en/application-dev/reference/apis/js-apis-screen-lock.md @@ -6,41 +6,41 @@ The **screenlock** module is a system module in OpenHarmony. It provides APIs fo > > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. - ## Modules to Import - ```js import screenlock from '@ohos.screenLock'; ``` - ## screenlock.isScreenLocked isScreenLocked(callback: AsyncCallback<boolean>): void Checks whether the screen is locked. This API uses an asynchronous callback to return the result. +> **NOTE** +> +>This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.isLocked9+](#screenlockislocked9) instead. + **System capability**: SystemCapability.MiscServices.ScreenLock **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the screen is locked; returns **false** otherwise.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| **Example** - ```js - screenlock.isScreenLocked((err, data)=>{ - if (err) { - console.error('isScreenLocked callback error -> ${JSON.stringify(err)}'); - return; - } - console.info('isScreenLocked callback success data -> ${JSON.stringify(data)}'); - }); - ``` - +```js +screenlock.isScreenLocked((err, data)=>{ + if (err) { + console.error('isScreenLocked callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('isScreenLocked callback success data -> ${JSON.stringify(data)}'); +}); +``` ## screenlock.isScreenLocked @@ -48,109 +48,155 @@ isScreenLocked(): Promise<boolean> Checks whether the screen is locked. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.isLocked9+](#screenlockislocked9) instead. + **System capability**: SystemCapability.MiscServices.ScreenLock **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the result.| +| Type | Description | +| ---------------------- | ------------------------------------------- | +| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| **Example** - ```js - screenlock.isScreenLocked().then((data) => { - console.log('isScreenLocked success: data -> ${JSON.stringify(data)}'); - }).catch((err) => { - console.error('isScreenLocked fail, promise: err -> ${JSON.stringify(err)}'); - }); - ``` +```js +screenlock.isScreenLocked().then((data) => { + console.log('isScreenLocked success: data -> ${JSON.stringify(data)}'); +}).catch((err) => { + console.error('isScreenLocked fail, promise: err -> ${JSON.stringify(err)}'); +}); +``` +## screenlock.isLocked9+ + +isLocked(): boolean + +Checks whether the screen is locked. This API returns the result synchronously. + +**System capability**: SystemCapability.MiscServices.ScreenLock + +**Return value** + +| Type | Description | +| ------- | ------------------------------------------------- | +| boolean | Returns **true** if the screen is locked; returns **false** otherwise.| + +**Example** + +```js +let isLocked = screenlock.isLocked(); +``` ## screenlock.isSecureMode isSecureMode(callback: AsyncCallback<boolean>): void +Checks whether the device is in secure mode. This API uses an asynchronous callback to return the result. -Checks whether a device is in secure mode. This API uses an asynchronous callback to return the result. - +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.isSecure9+](#screenlockissecure9) instead. **System capability**: SystemCapability.MiscServices.ScreenLock - **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the device is in secure mode; returns **false** otherwise.| +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ------------------------ | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| **Example** - ```js - screenlock.isSecureMode((err, data)=>{ - if (err) { - console.error('isSecureMode callback error -> ${JSON.stringify(err)}'); - return; - } - console.info('isSecureMode callback success data -> ${JSON.stringify(err)}'); - }); - ``` - +```js +screenlock.isSecureMode((err, data)=>{ + if (err) { + console.error('isSecureMode callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('isSecureMode callback success data -> ${JSON.stringify(err)}'); +}); +``` ## screenlock.isSecureMode isSecureMode(): Promise<boolean> -Checks whether a device is in secure mode. This API uses a promise to return the result. +Checks whether the device is in secure mode. This API uses a promise to return the result. + +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.isSecure9+](#screenlockissecure9) instead. **System capability**: SystemCapability.MiscServices.ScreenLock **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the result.| +| Type | Description | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | Promise used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| **Example** - ```js - screenlock.isSecureMode().then((data) => { - console.log('isSecureMode success: data->${JSON.stringify(data)}'); - }).catch((err) => { - console.error('isSecureMode fail, promise: err->${JSON.stringify(err)}'); - }); - ``` +```js +screenlock.isSecureMode().then((data) => { + console.log('isSecureMode success: data->${JSON.stringify(data)}'); +}).catch((err) => { + console.error('isSecureMode fail, promise: err->${JSON.stringify(err)}'); +}); +``` + +## screenlock.isSecure9+ + +isSecure(): boolean +Checks whether the device is in secure mode. + +**System capability**: SystemCapability.MiscServices.ScreenLock + +**Return value** + +| Type | Description | +| ------- | ------------------------------------------------------------ | +| boolean | The value **true** means that the device is in secure mode, and **false** means the opposite.| + +**Example** + +```js +let isSecure = screenlock.isSecure(); +``` ## screenlock.unlockScreen unlockScreen(callback: AsyncCallback<void>): void - Unlocks the screen. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.unlock9+](#screenlockunlock9) instead. **System capability**: SystemCapability.MiscServices.ScreenLock - **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | +| Name | Type | Mandatory| Description | +| -------- | ------------- | ---- | --------------- | | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation fails, an error message is returned.| **Example** - ```js - screenlock.unlockScreen((err) => { - if (err) { - console.error('unlockScreen callback error -> ${JSON.stringify(err)}'); - return; - } - console.info('unlockScreen callback success'); - }); - ``` - +```js +screenlock.unlockScreen((err) => { + if (err) { + console.error('unlockScreen callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('unlockScreen callback success'); +}); +``` ## screenlock.unlockScreen @@ -158,80 +204,131 @@ unlockScreen(): Promise<void> Unlocks the screen. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [screenlock.unlock9+](#screenlockunlock9) instead. + **System capability**: SystemCapability.MiscServices.ScreenLock **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return the result.| +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| **Example** - ```js - screenlock.unlockScreen().then(() => { - console.log('unlockScreen success'); - }).catch((err) => { - console.error('unlockScreen fail, promise: err->${JSON.stringify(err)}'); - }); - ``` +```js +screenlock.unlockScreen().then(() => { + console.log('unlockScreen success'); +}).catch((err) => { + console.error('unlockScreen fail, promise: err->${JSON.stringify(err)}'); +}); +``` +## screenlock.unlock9+ -## screenlock.lockScreen9+ +unlock(callback: AsyncCallback<boolean>): void -lockScreen(callback: AsyncCallback<boolean>): void +Unlocks the screen. This API uses an asynchronous callback to return the result. +**System capability**: SystemCapability.MiscServices.ScreenLock -Locks the screen. This API uses an asynchronous callback to return the result. +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ------------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| + +**Example** + +```js +screenlock.unlock((err,data) => { + if (err) { + console.error('unlock error -> ${JSON.stringify(err)}'); + return; + } + console.info('unlock success data -> ${JSON.stringify(data)}'); +}); +``` + +## screenlock.unlock9+ + +unlock(): Promise<boolean> + +Unlocks the screen. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.ScreenLock + +**Return value** +| Type | Description | +| ------------------- | ------------------------------------------------------------ | +| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| + +**Example** + +```js +screenlock.unlock().then((data) => { + console.log('unlock success'); +}).catch((err) => { + console.error('unlock fail, : err->${JSON.stringify(err)}'); +}); +``` + +## screenlock.lock9+ + +lock(callback: AsyncCallback<boolean>): void + +Locks the screen. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation fails, an error message is returned.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ---------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| **Example** - ```js - screenlock.lockScreen((err) => { - if (err) { - console.error('lockScreen callback error -> ${JSON.stringify(err)}'); - return; - } - console.info('lockScreen callback success'); - }); - ``` +```js +screenlock.lock((err,data) => { + if (err) { + console.error('lock callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('lock callback success'); +}); +``` -## screenlock.lockScreen9+ +## screenlock.lock9+ -lockScreen(): Promise<boolean> +lock(): Promise<boolean> Locks the screen. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return the result.| +| Type | Description | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| **Example** - ```js - screenlock.lockScreen().then(() => { - console.log('lockScreen success'); - }).catch((err) => { - console.error('lockScreen fail, promise: err->${JSON.stringify(err)}'); - }); - ``` +```js +screenlock.lock().then((data) => { + console.log('lock success'); +}).catch((err) => { + console.error('lock fail, promise: err->${JSON.stringify(err)}'); +}); +``` ## EventType @@ -239,22 +336,22 @@ Defines the system event type. **System capability**: SystemCapability.MiscServices.ScreenLock -| Name| Description| -| -------- | -------- | -| beginWakeUp | Wakeup starts when the event starts.| -| endWakeUp | Wakeup ends when the event ends.| -| beginScreenOn | Screen turn-on starts when the event starts.| -| endScreenOn | Screen turn-on ends when the event ends.| -| beginScreenOff | Screen turn-off starts when the event starts.| -| endScreenOff | Screen turn-off ends when the event ends.| -| unlockScreen | The screen is unlocked.| -| lockScreen | The screen is locked.| -| beginExitAnimation | Animation starts to exit.| -| beginSleep | The screen enters sleep mode.| -| endSleep | The screen exits sleep mode.| -| changeUser | The user is switched.| -| screenlockEnabled | Screen lock is enabled.| -| serviceRestart | The screen lock service is restarted.| +| Event Type | Description | +| ------------------ | ------------------------ | +| beginWakeUp | Wakeup starts when the event starts.| +| endWakeUp | Wakeup ends when the event ends.| +| beginScreenOn | Screen turn-on starts when the event starts.| +| endScreenOn | Screen turn-on ends when the event ends.| +| beginScreenOff | Screen turn-off starts when the event starts.| +| endScreenOff | Screen turn-off ends when the event ends.| +| unlockScreen | The screen is unlocked. | +| lockScreen | The screen is locked. | +| beginExitAnimation | Animation starts to exit. | +| beginSleep | The screen enters sleep mode. | +| endSleep | The screen exits sleep mode. | +| changeUser | The user is switched. | +| screenlockEnabled | Screen lock is enabled. | +| serviceRestart | The screen lock service is restarted. | ## SystemEvent @@ -263,10 +360,10 @@ Defines the structure of the system event callback. **System capability**: SystemCapability.MiscServices.ScreenLock -| Name| Description| -| -------- | -------- | -| eventType | System event type.| -| params | System event parameters.| +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | ------------- | +| eventType | [EventType](#eventtype) | Yes | System event type.| +| params | string | Yes | System event parameters.| ## screenlock.onSystemEvent9+ @@ -276,87 +373,84 @@ Registers a callback for system events related to screen locking. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | Callback\ | Yes| Callback for system events related to screen locking| +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------- | ---- | ---------------------------- | +| callback | Callback\<[SystemEvent](#systemevent)> | Yes | Callback for system events related to screen locking.| **Return value** -| Type | Description | -| ------- | -------------------------------------------- | -| boolean | The value **true** means that the callback is registered successfully, and **false** means the opposite.| +| Type | Description | +| ------- | ------------------------------------------------- | +| boolean | Returns **true** if the callback is registered successfully; returns **false** otherwise.| **Example** - ```js - let isSuccess = screenlock.onSystemEvent((err, event)=>{ - console.log(`onSystemEvent:callback:${event.eventType}`) - if (err) { - console.log(`onSystemEvent callback error -> ${JSON.stringify(err)}`); - } - }); - if (!isSuccess) { - console.log(`onSystemEvent result is false`) - } - ``` +```js +let isSuccess = screenlock.onSystemEvent((event)=>{ + console.log(`onSystemEvent:callback:${event.eventType}`) +}); +if (!isSuccess) { + console.log(`onSystemEvent result is false`) +} +``` ## screenlock.sendScreenLockEvent9+ -sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback\): void +sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback\): void Sends an event to the screen lock service. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | String | Yes| Event type.
- **"unlockScreenResult"**: Screen unlock result.
- **"screenDrawDone"**: Screen drawing is complete.| -| parameter | number | Yes| Screen unlock status.
- **0**: The unlock is successful.
- **1**: The unlock failed.
- **2**: The unlock was canceled.| -| callback | AsyncCallback\ | Yes| Callback used to return the result.| +| Name | Type | Mandatory| Description | +| --------- | ------------------------ | ---- | -------------------- | +| event | String | Yes | Event type.
- **"unlockScreenResult"**: Screen unlock result.
- **"screenDrawDone"**: Screen drawing is complete.| +| parameter | number | Yes | Screen unlock status.
- **0**: The unlock is successful.
- **1**: The unlock failed.
- **2**: The unlock was canceled.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that the operation is successful, and **false** means the opposite. | **Example** - ```js - screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { - console.log('sending result:' + result); - }); - ``` +```js +screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { + console.log('sending result:' + result); +}); +``` ## screenlock.sendScreenLockEvent9+ -sendScreenLockEvent(event: String, parameter: number): Promise\ +sendScreenLockEvent(event: String, parameter: number): Promise\ Sends an event to the screen lock service. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | String | Yes| Event type.
- **"unlockScreenResult"**: Screen unlock result.
- **"screenDrawDone"**: Screen drawing is complete.| -| parameter | number | Yes| Screen unlock status.
- **0**: The unlock is successful.
- **1**: The unlock fails.
- **2**: The unlock is canceled.| +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | --------------------------------------- | +| event | String | Yes | Event type.
- **"unlockScreenResult"**: Screen unlock result.
- **"screenDrawDone"**: Screen drawing is complete.| +| parameter | number | Yes | Screen unlock status.
- **0**: The unlock is successful.
- **1**: The unlock failed.
- **2**: The unlock was canceled.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise\ | Promise used to return the result.| +| Type | Description | +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.| **Example** - ```js - screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { - console.log('sending result:' + result); - }); - ``` +```js +screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { + console.log('sending result:' + result); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-wallpaper.md b/en/application-dev/reference/apis/js-apis-wallpaper.md index 8c6ca80a6161e29fd1eb4ccd5e3a4f9f7841556b..b7a9bad454b15ce99e38ff407df3aa4dc5e7b653 100644 --- a/en/application-dev/reference/apis/js-apis-wallpaper.md +++ b/en/application-dev/reference/apis/js-apis-wallpaper.md @@ -17,14 +17,14 @@ import wallpaper from '@ohos.wallpaper'; ## WallpaperType -Defines the wallpaper type. +Enumerates the wallpaper types. **System capability**: SystemCapability.MiscServices.Wallpaper -| Name| Description| -| -------- | -------- | -| WALLPAPER_LOCKSCREEN | Lock screen wallpaper.| -| WALLPAPER_SYSTEM | Home screen wallpaper.| +| Name| Value|Description| +| -------- | -------- |-------- | +| WALLPAPER_SYSTEM | 0 |Home screen wallpaper.| +| WALLPAPER_LOCKSCREEN | 1 |Lock screen wallpaper.| ## wallpaper.getColors @@ -33,6 +33,10 @@ getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<Rgba Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -61,6 +65,10 @@ getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>> Obtains the main color information of the wallpaper of the specified type. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -86,12 +94,43 @@ Obtains the main color information of the wallpaper of the specified type. This ``` +## wallpaper.getColorsSync9+ + +getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor> + +Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Array<[RgbaColor](#rgbacolor)> | Promise used to return the main color information of the wallpaper.| + +**Example** + + ```js + var colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM); + ``` + + ## wallpaper.getId getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -120,8 +159,11 @@ getId(wallpaperType: WallpaperType): Promise<number> Obtains the ID of the wallpaper of the specified type. This API uses a promise to return the result. -**System capability**: SystemCapability.MiscServices.Wallpaper +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead. +**System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -146,12 +188,43 @@ Obtains the ID of the wallpaper of the specified type. This API uses a promise t ``` +## wallpaper.getIdSync9+ + +getIdSync(wallpaperType: WallpaperType): number + +Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | ID of the wallpaper. If this type of wallpaper is configured, a number greater than or equal to **0** is returned. Otherwise, **-1** is returned. The value ranges from -1 to 2^31-1.| + +**Example** + + ```js + var id = wallpaper.getIdSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM); + ``` + + ## wallpaper.getMinHeight getMinHeight(callback: AsyncCallback<number>): void Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -179,8 +252,11 @@ getMinHeight(): Promise<number> Obtains the minimum height of this wallpaper. This API uses a promise to return the result. -**System capability**: SystemCapability.MiscServices.Wallpaper +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead. +**System capability**: SystemCapability.MiscServices.Wallpaper **Return value** @@ -199,14 +275,38 @@ Obtains the minimum height of this wallpaper. This API uses a promise to return ``` +## wallpaper.getMinHeightSync9+ + +getMinHeightSync(): number + +Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | Promise used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead.| + +**Example** + + ```js + var minHeight = wallpaper.getMinHeightSync(); + ``` + + ## wallpaper.getMinWidth getMinWidth(callback: AsyncCallback<number>): void Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.MiscServices.Wallpaper +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead. +**System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** @@ -233,13 +333,17 @@ getMinWidth(): Promise<number> Obtains the minimum width of this wallpaper. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Return value** | Type| Description| | -------- | -------- | -| Promise<number> | Promised used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| +| Promise<number> | Promise used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| **Example** @@ -252,19 +356,44 @@ Obtains the minimum width of this wallpaper. This API uses a promise to return t ``` +## wallpaper.getMinWidthSync9+ + +getMinWidthSync(): number + +Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | Promise used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| + +**Example** + + ```js + var minWidth = wallpaper.getMinWidthSync(); + ``` + + ## wallpaper.isChangePermitted isChangePermitted(callback: AsyncCallback<boolean>): void Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the application is allowed to change the wallpaper for the current user; returns **false** otherwise.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return whether to allow the application to change the wallpaper for the current user. The value **true** means that the operation is allowed, and **false** means the opposite.| **Example** @@ -285,13 +414,17 @@ isChangePermitted(): Promise<boolean> Checks whether to allow the application to change the wallpaper for the current user. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Return value** | Type| Description| | -------- | -------- | -| Promise<boolean> | Promise used to return the result. Returns **true** if the application is allowed to change the wallpaper for the current user; returns **false** otherwise.| +| Promise<boolean> | Promise used to return whether to allow the application to change the wallpaper for the current user. The value **true** means that the operation is allowed, and **false** means the opposite.| **Example** @@ -304,19 +437,44 @@ Checks whether to allow the application to change the wallpaper for the current ``` +## wallpaper.isChangeAllowed9+ + +isChangeAllowed(): boolean + +Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Whether to allow the application to change the wallpaper for the current user. The value **true** means that the operation is allowed, and **false** means the opposite.| + +**Example** + + ```js + var isChangeAllowed = wallpaper.isChangeAllowed(); + ``` + + ## wallpaper.isOperationAllowed isOperationAllowed(callback: AsyncCallback<boolean>): void Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the user is allowed to set wallpapers; returns **false** otherwise.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.| **Example** @@ -337,13 +495,17 @@ isOperationAllowed(): Promise<boolean> Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead. + **System capability**: SystemCapability.MiscServices.Wallpaper **Return value** | Type| Description| | -------- | -------- | -| Promise<boolean> | Promise used to return the result. Returns **true** if the user is allowed to set wallpapers; returns **false** otherwise.| +| Promise<boolean> | Promise used to return whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.| **Example** @@ -356,12 +518,37 @@ Checks whether the user is allowed to set wallpapers. This API uses a promise to ``` +## wallpaper.isUserChangeAllowed9+ + +isUserChangeAllowed(): boolean + +Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.| + +**Example** + + ```js + var isUserChangeAllowed = wallpaper.isUserChangeAllowed(); + ``` + + ## wallpaper.reset reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead. + **Required permissions**: ohos.permission.SET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -392,6 +579,10 @@ reset(wallpaperType: WallpaperType): Promise<void> Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead. + **Required permissions**: ohos.permission.SET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -419,12 +610,79 @@ Resets the wallpaper of the specified type to the default wallpaper. This API us ``` +## wallpaper.restore9+ + +restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void + +Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned.| + +**Example** + + ```js + wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to restore because: ` + JSON.stringify(error)); + return; + } + console.log(`success to restore.`); + }); + ``` + + +## wallpaper.restore9+ + +restore(wallpaperType: WallpaperType): Promise<void> + +Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.| + +**Example** + + ```js + wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to restore.`); + }).catch((error) => { + console.error(`failed to restore because: ` + JSON.stringify(error)); + }); + ``` + + ## wallpaper.setWallpaper setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead. + **Required permissions**: ohos.permission.SET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -433,7 +691,7 @@ Sets a specified source as the wallpaper of a specified type. This API uses an a | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| source | string \|[PixelMap](js-apis-image.md#pixelmap7) | | URI of a JPEG or PNG file, or bitmap of a PNG file.| +| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.| | wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.| @@ -479,6 +737,10 @@ setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Pro Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead. + **Required permissions**: ohos.permission.SET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -487,7 +749,7 @@ Sets a specified source as the wallpaper of a specified type. This API uses a pr | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| source | string \|[PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.| +| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.| | wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| **Return value** @@ -499,7 +761,7 @@ Sets a specified source as the wallpaper of a specified type. This API uses a pr **Example** ```js - // The source type is string. + //The source type is string. let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { console.log(`success to setWallpaper.`); @@ -527,12 +789,126 @@ Sets a specified source as the wallpaper of a specified type. This API uses a pr }); ``` + +## wallpaper.setImage9+ + +setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void + +Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.| +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.| + +**Example** + + ```js + //The source type is string. + let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; + wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to setImage because: ` + JSON.stringify(error)); + return; + } + console.log(`success to setImage.`); + }); + + // The source type is image.PixelMap. + import image from '@ohos.multimedia.image'; + let imageSource = image.createImageSource("file://" + wallpaperPath); + let opts = { + "desiredSize": { + "height": 3648, + "width": 2736 + } + }; + imageSource.createPixelMap(opts).then((pixelMap) => { + wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to setImage because: ` + JSON.stringify(error)); + return; + } + console.log(`success to setImage.`); + }); + }).catch((error) => { + console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.setImage9+ + +setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void> + +Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.| +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.| + +**Example** + + ```js + //The source type is string. + let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; + wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to setImage.`); + }).catch((error) => { + console.error(`failed to setImage because: ` + JSON.stringify(error)); + }); + + // The source type is image.PixelMap. + import image from '@ohos.multimedia.image'; + let imageSource = image.createImageSource("file://" + wallpaperPath); + let opts = { + "desiredSize": { + "height": 3648, + "width": 2736 + } + }; + imageSource.createPixelMap(opts).then((pixelMap) => { + wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to setImage.`); + }).catch((error) => { + console.error(`failed to setImage because: ` + JSON.stringify(error)); + }); + }).catch((error) => { + console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); + }); + ``` + + ## wallpaper.getFile8+ getFile(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [wallpaper.getFileSync9+](#wallpapergetfilesync9) instead. + **Required permissions**: ohos.permission.GET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -562,6 +938,10 @@ getFile(wallpaperType: WallpaperType): Promise<number> Obtains the wallpaper of the specified type. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [wallpaper.getFileSync9+](#wallpapergetfilesync9) instead. + **Required permissions**: ohos.permission.GET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -589,12 +969,45 @@ Obtains the wallpaper of the specified type. This API uses a promise to return t ``` +## wallpaper.getFileSync9+ + +getFileSync(wallpaperType: WallpaperType): number; + +Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | Promise used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned.| + +**Example** + + ```js + var file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM); + ``` + + ## wallpaper.getPixelMap getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getImage9+](#wallpapergetimage9) instead. + **Required permissions**: ohos.permission.GET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -606,7 +1019,7 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses an | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| +| callback | AsyncCallback<image.PixelMap> | Yes| Callback used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| **Example** @@ -624,6 +1037,10 @@ getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap> Obtains the pixel map for the wallpaper of the specified type. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getImage9+](#wallpapergetimage9) instead. + **Required permissions**: ohos.permission.GET_WALLPAPER **System capability**: SystemCapability.MiscServices.Wallpaper @@ -640,7 +1057,7 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses a p | Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| +| Promise<image.PixelMap> | Promise used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| **Example** @@ -655,7 +1072,73 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses a p ``` -## wallpaper.on('colorChange') +## wallpaper.getImage9+ + +getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; + +Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| +| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes| Callback used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| + +**Example** + + ```js + wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (err, data) { + console.info('wallpaperXTS ===> testgetImageCallbackSystem err : ' + JSON.stringify(err)); + console.info('wallpaperXTS ===> testgetImageCallbackSystem data : ' + JSON.stringify(data)); + }); + ``` + + +## wallpaper.getImage9+ + +getImage(wallpaperType: WallpaperType): Promise<image.PixelMap> + +Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_WALLPAPER + +**System capability**: SystemCapability.MiscServices.Wallpaper + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.| + +**Example** + + ```js + wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.info('wallpaperXTS ===> testgetImagePromiseSystem data : ' + data); + console.info('wallpaperXTS ===> testgetImagePromiseSystem data : ' + JSON.stringify(data)); + }).catch((err) => { + console.info('wallpaperXTS ===> testgetImagePromiseSystem err : ' + err); + console.info('wallpaperXTS ===> testgetImagePromiseSystem err : ' + JSON.stringify(err)); + }); + ``` + + +## wallpaper.on('colorChange')9+ on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void @@ -680,7 +1163,7 @@ Subscribes to the wallpaper color change event. ``` -## wallpaper.off('colorChange') +## wallpaper.off('colorChange')9+ off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void