From e19acd418c0162134fb0c83c41aed47e40798f14 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Wed, 28 Sep 2022 17:57:52 +0800 Subject: [PATCH] Update docs (9054) Signed-off-by: ester.zhou --- en/application-dev/faqs/faqs-ui-ets.md | 2 +- en/application-dev/faqs/faqs-ui-js.md | 2 +- .../apis/js-apis-accessibility-config.md | 364 +++++++++++++ .../reference/apis/js-apis-inputmethod.md | 80 ++- .../apis/js-apis-inputmethodengine.md | 489 ++++++++++++++---- .../reference/apis/js-apis-screen-lock.md | 120 ++--- 6 files changed, 837 insertions(+), 220 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-accessibility-config.md diff --git a/en/application-dev/faqs/faqs-ui-ets.md b/en/application-dev/faqs/faqs-ui-ets.md index fd21421cd9..86a05c9185 100644 --- a/en/application-dev/faqs/faqs-ui-ets.md +++ b/en/application-dev/faqs/faqs-ui-ets.md @@ -202,7 +202,7 @@ struct DialogTest { Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 -The **\** component is a scrollable container. By default, it taks up the entire screen height. When any component with a fixed height takes up part of the screen height, you need to explicitly specify **layoutWeight(1)** for the parent container of the **\** component to take up the remaining height instead of the entire screen height. +The **\** component is a scrollable container. By default, it takes up the entire screen height. When any component with a fixed height takes up part of the screen height, you need to explicitly specify **layoutWeight(1)** for the parent container of the **\** component to take up the remaining height instead of the entire screen height. ## How do I center child components in a grid container? diff --git a/en/application-dev/faqs/faqs-ui-js.md b/en/application-dev/faqs/faqs-ui-js.md index 5d39db3319..7d4ae1dcb8 100644 --- a/en/application-dev/faqs/faqs-ui-js.md +++ b/en/application-dev/faqs/faqs-ui-js.md @@ -30,7 +30,7 @@ let options = {trim : false, declarationKey:"_declaration", nameKey : "_name", elementsKey : "_elements"} let result:any = conv.convert(xml, options) // Convert fields in the XML file into JavaScript objects. console.log('Test: ' + JSON.stringify(result)) -console.log('Test: ' + result._declaration._attributes.version) // vesion field in XML file +console.log('Test: ' + result._declaration._attributes.version) // version field in XML file console.log('Test: ' + result._elements[0]._elements[0]._elements[0]._text) // title field in XML file ``` diff --git a/en/application-dev/reference/apis/js-apis-accessibility-config.md b/en/application-dev/reference/apis/js-apis-accessibility-config.md new file mode 100644 index 0000000000..71517bfb32 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-accessibility-config.md @@ -0,0 +1,364 @@ +# System Accessibility Configuration + +The **config** module allows you to configure system accessibility features, including accessibility extension, high-contrast text, mouse buttons, and captions. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> The APIs provided by this module are system APIs. + +## Modules to Import + +```typescript +import config from "@ohos.accessibility.config"; +``` + +## Attributes + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| highContrastText | [Config](#config)\| Yes| Yes| Whether to enable high-contrast text.| +| invertColor | [Config](#config)\| Yes| Yes| Whether to enable color inversion.| +| daltonizationColorFilter | [Config](#config)<[DaltonizationColorFilter](#daltonizationcolorfilter)>| Yes| Yes| Configuration of the daltonization filter.| +| contentTimeout | [Config](#config)\| Yes| Yes| Recommended duration for content display. The value ranges from 0 to 5000, in milliseconds.| +| animationOff | [Config](#config)\| Yes| Yes| Whether to enable animation.| +| brightnessDiscount | [Config](#config)\| Yes| Yes| Brightness discount. The value ranges from 0 to 1.0.| +| mouseKey | [Config](#config)\| Yes| Yes| Whether to enable the mouse button feature.| +| mouseAutoClick | [Config](#config)\| Yes| Yes| Interval for the automatic mouse clicks. The value ranges from 0 to 5000, in milliseconds.| +| shortkey | [Config](#config)\| Yes| Yes| Whether to enable the accessibility extension shortcut key.| +| shortkeyTarget | [Config](#config)\| Yes| Yes| Target application for the accessibility extension shortcut key. The value format is bundleName/abilityName.| +| captions | [Config](#config)\| Yes| Yes| Whether to enable captions.| +| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](./js-apis-accessibility.md#captionsstyle8)>| Yes| Yes| Captions style.| + +## enableAbility + +enableAbility(name: string, capability: Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>): Promise<void>; + +Enables an accessibility extension ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| +| capability | Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>) | Yes| Capability of the accessibility extension ability.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the execution result.| + +**Example** + + ```typescript + config.enableAbility("com.ohos.example/axExtension", ['retrieve']) + .then(() => { + console.info('enable succeed'); + }).catch((error) => { + console.error('enable failed'); + }); + ``` + +## enableAbility + +enableAbility(name: string, capability: Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>, callback: AsyncCallback<void>): void; + +Enables an accessibility extension ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| +| capability | Array<[accessibility.Capability](./js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| +| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +**Example** + + ```typescript + config.enableAbility("com.ohos.example/axExtension", ['retrieve'], (err, data) => { + if (err) { + console.error('enable failed'); + return; + } + console.info('enable succeed'); + }) + ``` + +## disableAbility + +disableAbility(name: string): Promise<void>; + +Disables an accessibility extension ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the execution result.| + +**Example** + + ```typescript + config.disableAbility("com.ohos.example/axExtension") + .then(() => { + console.info('disable succeed'); + }).catch((error) => { + console.error('disable failed'); + }); + ``` + +## disableAbility + +disableAbility(name: string, callback: AsyncCallback<void>): void; + +Disables an accessibility extension ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| +| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +**Example** + + ```typescript + config.disableAbility("com.ohos.example/axExtension", (err, data) => { + if (err) { + console.error('disable failed'); + return; + } + console.info('disable succeed'); + }) + ``` + +## on('enableAbilityListsStateChanged') + +on(type: 'enableAbilityListsStateChanged', callback: Callback<void>): void; + +Adds a listener for changes in the list of enabled accessibility extension abilities. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Listening type. The value is fixed at **'enableAbilityListsStateChanged'**, indicating that the changes in the list of enabled accessibility extension abilities.| +| callback | Callback<void> | Yes| Callback invoked when the list of enabled accessibility extension abilities changes.| + +**Example** + + ```typescript + config.on('enableAbilityListsStateChanged',() => { + console.info('ax extension ability enable list changed'); + }); + ``` + +## off('enableAbilityListsStateChanged') + +off(type: 'enableAbilityListsStateChanged', callback?: Callback<void>): void; + +Cancels the listener for changes in the list of enabled accessibility extension abilities. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | No| Listening type. The value is fixed at **'enableAbilityListsStateChanged'**, indicating that the changes in the list of enabled accessibility extension abilities.| +| callback | Callback<void> | No| Callback invoked when the list of enabled accessibility extension abilities changes.| + +**Example** + + ```typescript + config.off('enableAbilityListsStateChanged'); + ``` + +## Config + +Implements configuration, acquisition, and listening for attributes. + +### set + +set(value: T): Promise<void>; + +Sets this attribute. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| value | T | Yes| Attribute value to set.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the execution result.| + +**Example** + + ```typescript + config.highContrastText.set(true) + .then(() => { + console.info('highContrastText set succeed'); + }).catch((error) => { + console.error('highContrastText set failed'); + }); + ``` + +### set + +set(value: T, callback: AsyncCallback<void>): void; + +Sets this attribute. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| value | T | Yes| Attribute value to set.| +| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +**Example** + + ```typescript + config.highContrastText.set(true, (err, data) => { + if (err) { + console.error('highContrastText set failed'); + return; + } + console.info('highContrastText set succeed'); + }) + ``` + +### get + +get(): Promise<T>; + +Obtains the value of this attribute. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<T> | Promise used to return the attribute value.| + +**Example** + + ```typescript + config.highContrastText.get() + .then((value) => { + console.info('highContrastText get succeed'); + }).catch((error) => { + console.error('highContrastText get failed'); + }); + ``` + +### get + +get(callback: AsyncCallback<T>): void; + +Obtains the value of this attribute. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the attribute value.| + +**Example** + + ```typescript + config.highContrastText.get((err, data) => { + if (err) { + console.error('highContrastText get failed'); + return; + } + console.info('highContrastText get succeed'); + }) + ``` + +### on + +on(callback: Callback<T>): void; + +Adds a listener for attribute changes. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | Callback<T> | Yes| Callback invoked when the attribute changes.| + +**Example** + + ```typescript + config.highContrastText.on(() => { + console.info('highContrastText changed'); + }); + ``` + +### off + +off(callback?: Callback<T>): void; + +Cancels the listener for attribute changes. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | Callback<T> | No| Callback invoked when the attribute changes.| + +**Example** + + ```typescript + config.highContrastText.off(); + ``` + +## DaltonizationColorFilter + +Enumerates the daltonization filters. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| Normal | Filter for normal users.| +| Protanomaly | Filter for protanomaly.| +| Deuteranomaly | Filter for deuteranomaly.| +| Tritanomaly | Filter for tritanomaly.| diff --git a/en/application-dev/reference/apis/js-apis-inputmethod.md b/en/application-dev/reference/apis/js-apis-inputmethod.md index f29975c5b4..924a630661 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod.md @@ -47,7 +47,7 @@ Obtains an **[InputMethodController](#inputmethodcontroller)** instance. | Type | Description | | ----------------------------------------------- | ------------------------ | -| [InputMethodController](#inputmethodcontroller) | Returns the current **InputMethodController** instance.| +| [InputMethodController](#inputmethodcontroller) | Current **InputMethodController** instance.| **Example** @@ -67,7 +67,7 @@ Obtains an **[InputMethodSetting](#inputmethodsetting8)** instance. | Type | Description | | ----------------------------------------- | ---------------------------- | -| [InputMethodSetting](#inputmethodsetting8) | Returns the current **InputMethodSetting** instance.| +| [InputMethodSetting](#inputmethodsetting8) | Current **InputMethodSetting** instance.| **Example** @@ -94,15 +94,15 @@ Switches to another input method. This API can be used only in the stage model. **Example** ```js -inputMethod.switchInputMethod({packageName:"com.example.kikakeyboard", methodId:"com.example.kikakeyboard"} ,(err,result) => { +inputMethod.switchInputMethod({packageName:'com.example.kikakeyboard', methodId:'com.example.kikakeyboard'} ,(err,result) => { if (err) { - console.error("switchInputMethod err: " + JSON.stringify(err)); + console.error('switchInputMethod err: ' + JSON.stringify(err)); return; } if (result) { - console.info("Success to switchInputMethod.(callback)"); + console.info('Success to switchInputMethod.(callback)'); } else { - console.error("Failed to switchInputMethod.(callback)"); + console.error('Failed to switchInputMethod.(callback)'); } }); ``` @@ -129,14 +129,14 @@ Switches to another input method. This API can be used only in the stage model. ```js -inputMethod.switchInputMethod({packageName:"com.example.kikakeyboard", methodId:"com.example.kikakeyboard"}).then((result) => { +inputMethod.switchInputMethod({packageName:'com.example.kikakeyboard', methodId:'com.example.kikakeyboard'}).then((result) => { if (result) { - console.info("Success to switchInputMethod.(promise)"); + console.info('Success to switchInputMethod.(promise)'); } else { - console.error("Failed to switchInputMethod.(promise)"); + console.error('Failed to switchInputMethod.(promise)'); } }).catch((err) => { - console.error("switchInputMethod promise err: " + err); + console.error('switchInputMethod promise err: ' + err); }) ``` ## inputMethod.getCurrentInputMethod9+ @@ -151,7 +151,7 @@ Obtains the current input method. This API synchronously returns the **Inputmeth | Type | Description | | -------------------------------------------- | ------------------------ | -| [InputmethodProperty](#inputmethodproperty8) | **InputmethodProperty** instance of the current input method. | +| [InputmethodProperty](#inputmethodproperty8) | **InputmethodProperty** instance of the current input method.| **Example** @@ -183,13 +183,13 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ```js InputMethodController.stopInput((error, result) => { if (error) { - console.error("failed to stopInput because: " + JSON.stringify(error)); + console.error('failed to stopInput because: ' + JSON.stringify(error)); return; } if (result) { - console.info("Success to stopInput.(callback)"); + console.info('Success to stopInput.(callback)'); } else { - console.error("Failed to stopInput.(callback)"); + console.error('Failed to stopInput.(callback)'); } }); ``` @@ -214,12 +214,12 @@ Hides the keyboard. This API uses a promise to return the result. If any paramet ```js InputMethodController.stopInput().then((result) => { if (result) { - console.info("Success to stopInput.(promise)"); + console.info('Success to stopInput.(promise)'); } else { - console.error("Failed to stopInput.(promise)"); + console.error('Failed to stopInput.(promise)'); } }).catch((err) => { - console.error("stopInput promise err: " + err); + console.error('stopInput promise err: ' + err); }) ``` @@ -241,7 +241,7 @@ Shows this soft keyboard. This API uses an asynchronous callback to return the r ```js InputMethodController.showSoftKeyboard((err) => { - if (err == undefined) { + if (err === undefined) { console.info('showSoftKeyboard success'); } else { console.error('showSoftKeyboard failed because : ' + JSON.stringify(err)); @@ -292,7 +292,7 @@ Hides this soft keyboard. This API uses an asynchronous callback to return the r ```js InputMethodController.hideSoftKeyboard((err) => { - if (err == undefined) { + if (err === undefined) { console.info('hideSoftKeyboard success'); } else { console.error('hideSoftKeyboard failed because : ' + JSON.stringify(err)); @@ -342,19 +342,17 @@ Obtains a list of activated or deactivated input methods. This API uses an async | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------- | ---- | ----------------------------- | | enable | boolean | Yes | Whether to return a list of activated input methods. The value **true** means to return a list of activated input methods, and **false** means to return a list of deactivated input methods. | -| callback | Array<[InputMethodProperty](#inputmethodproperty8)> | Yes | Callback used to return a list of activated or deactivated input methods. | +| callback | Array<[InputMethodProperty](#inputmethodproperty8)> | Yes | Callback used to return a list of activated or deactivated input methods.| **Example** ```js -imeList: Array = null InputMethodSetting.listInputMethod(true, (err,data) => { if (err) { - console.error("listInputMethod failed because: " + JSON.stringify(err)); + console.error('listInputMethod failed because: ' + JSON.stringify(err)); return; } - console.log("listInputMethod success"); - this.imeList = data; + console.log('listInputMethod success'); }); ``` @@ -376,17 +374,15 @@ Obtains a list of activated or deactivated input methods. This API uses a promis | Type | Description | | ------------------------------------------------------------ | ----------------------------- | -| Promise> | Promise used to return a list of activated or deactivated input methods. | +| Promise> | Promise used to return a list of activated or deactivated input methods.| **Example** ```js -imeList: Array = null InputMethodSetting.listInputMethod(true).then((data) => { - console.info("listInputMethod success"); - this.imeList = data; + console.info('listInputMethod success'); }).catch((err) => { - console.error("listInputMethod promise err: " + err); + console.error('listInputMethod promise err: ' + err); }) ``` @@ -407,14 +403,12 @@ Obtains a list of installed input methods. This API uses an asynchronous callbac **Example** ```js -imeList: Array = null InputMethodSetting.listInputMethod((err,data) => { if (err) { - console.error("listInputMethod failed because: " + JSON.stringify(err)); + console.error('listInputMethod failed because: ' + JSON.stringify(err)); return; } - console.log("listInputMethod success"); - this.imeList = data; + console.log('listInputMethod success'); }); ``` @@ -435,12 +429,10 @@ Obtains a list of installed input methods. This API uses a promise to return the **Example** ```js -imeList: Array = null InputMethodSetting.listInputMethod().then((data) => { - console.info("listInputMethod success"); - this.imeList = data; + console.info('listInputMethod success'); }).catch((err) => { - console.error("listInputMethod promise err: " + err); + console.error('listInputMethod promise err: ' + err); }) ``` @@ -463,20 +455,20 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono ```js InputMethodSetting.displayOptionalInputMethod((err) => { if (err) { - console.error("displayOptionalInputMethod failed because: " + JSON.stringify(err)); + console.error('displayOptionalInputMethod failed because: ' + JSON.stringify(err)); return; } - console.info("displayOptionalInputMethod success"); + console.info('displayOptionalInputMethod success'); }); ``` ### displayOptionalInputMethod -displayOptionalInputMethod(): Promise<void> + displayOptionalInputMethod(): Promise<void> -Displays a dialog box for selecting an input method. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown. + Displays a dialog box for selecting an input method. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown. -**System capability**: SystemCapability.MiscServices.InputMethodFramework + **System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** @@ -488,8 +480,8 @@ Displays a dialog box for selecting an input method. This API uses a promise to ```js InputMethodSetting.displayOptionalInputMethod().then(() => { - console.info("displayOptionalInputMethod success.(promise)"); + console.info('displayOptionalInputMethod success.(promise)'); }).catch((err) => { - console.error("displayOptionalInputMethod promise err: " + err); + console.error('displayOptionalInputMethod promise err: ' + err); }) ``` diff --git a/en/application-dev/reference/apis/js-apis-inputmethodengine.md b/en/application-dev/reference/apis/js-apis-inputmethodengine.md index 55e702cd05..7ae3556672 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethodengine.md +++ b/en/application-dev/reference/apis/js-apis-inputmethodengine.md @@ -46,6 +46,11 @@ Provides the constants. | FLAG_SINGLE_LINE | number | Yes| No| The edit box allows only single-line input.| | DISPLAY_MODE_PART | number | Yes| No| The edit box is displayed in half-screen mode.| | DISPLAY_MODE_FULL | number | Yes| No| The edit box is displayed in full screen.| +| CURSOR_UP9+ | number | Yes| No| The caret moves upward.| +| CURSOR_DOWN9+ | number | Yes| No| The caret moves downward.| +| CURSOR_LEFT9+ | number | Yes| No| The caret moves leftward.| +| CURSOR_RIGHT9+ | number | Yes| No| The caret moves rightward.| +| WINDOW_TYPE_INPUT_METHOD_FLOAT9+ | number | Yes| No| The input method is displayed in a floating window.| ## inputMethodEngine.getInputMethodEngine @@ -95,7 +100,7 @@ In the following API examples, you must first use [getInputMethodEngine](#getInp on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void -Listens for the input method binding event. This API uses a callback to return the result. +Listens for the input method binding event. This API uses a callback to return the result. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -119,7 +124,7 @@ Listens for the input method binding event. This API uses a callback to return t off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void -Cancels listening for the input method binding event. +Cancels listening for the input method binding event. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -135,14 +140,108 @@ Cancels listening for the input method binding event. **Example** ```js - InputMethodEngine.off('inputStart'); + InputMethodEngine.off('inputStart', (kbController, textInputClient) => { + console.log('delete inputStart notification.'); + }); + ``` + +### on('inputStop')9+ + +on(type: 'inputStop', callback: () => void): void + +Listens for the input method stop event. This API uses a callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'inputStop'**, which indicates listening for the input method stop event.| +| callback | void | Yes | Callback used to return the result. | + +**Example** + + ```js +InputMethodEngine.getInputMethodEngine().on('inputStop', () => { + console.log('inputMethodEngine inputStop'); +}); + ``` + +### off('inputStop')9+ + +off(type: 'inputStop', callback: () => void): void + +Cancels listening for the input method stop event. This API uses a callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'inputStop'**, which indicates listening for the input method stop event.| +| callback | void | Yes | Callback used to return the result. | + +**Example** + + ```js +InputMethodEngine.getInputMethodEngine().off('inputStop', () => { + console.log('inputMethodEngine delete inputStop notification.'); +}); + ``` + +### on('setCallingWindow')9+ + +on(type: 'setCallingWindow', callback: (wid:number) => void): void + +Listens for the window invocation setting event. This API uses a callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'setCallingWindow'**, which indicates listening for the window invocation setting event.| +| callback | number | Yes | Window ID of the caller. | + +**Example** + + ```js +InputMethodEngine.getInputMethodEngine().on('setCallingWindow', (wid) => { + console.log('inputMethodEngine setCallingWindow'); +}); + ``` + +### off('setCallingWindow')9+ + +off(type: 'setCallingWindow', callback: (wid:number) => void): void + +Cancels listening for the window invocation setting event. This API uses a callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'setCallingWindow'**, which indicates listening for the window invocation setting event.| +| callback | number | Yes | Window ID of the caller. | + +**Example** + + ```js +InputMethodEngine.getInputMethodEngine().off('setCallingWindow', () => { + console.log('inputMethodEngine delete setCallingWindow notification.'); +}); ``` ### on('keyboardShow'|'keyboardHide') on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void -Listens for an input method event. +Listens for an input method event. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -150,14 +249,17 @@ Listens for an input method event. | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| +| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the keyboard.
- The value **'keyboardHide'** means to listen for hiding of the keyboard. | | callback | void | No | Callback used to return the result. | **Example** ```js - InputMethodEngine.on('keyboardShow', (err) => { - console.info('keyboardShow'); + InputMethodEngine.on('keyboardShow', () => { + console.log('inputMethodEngine keyboardShow.'); + }); + InputMethodEngine.on('keyboardHide', () => { + console.log('inputMethodEngine keyboardHide.'); }); ``` @@ -165,7 +267,7 @@ Listens for an input method event. off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void -Cancels listening for an input method event. +Cancels listening for an input method event. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -173,13 +275,18 @@ Cancels listening for an input method event. | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| +| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the keyboard.
- The value **'keyboardHide'** means to listen for hiding of the keyboard.| | callback | void | No | Callback used to return the result. | **Example** ```js - InputMethodEngine.off('keyboardShow'); + InputMethodEngine.off('keyboardShow', () => { + console.log('inputMethodEngine delete keyboardShow notification.'); + }); + InputMethodEngine.off('keyboardHide', () => { + console.log('inputMethodEngine delete keyboardHide notification.'); + }); ``` @@ -191,7 +298,7 @@ In the following API examples, you must first use [createKeyboardDelegate](#crea on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void -Listens for a hard keyboard even. This API uses a callback to return the key information. +Listens for a hard keyboard even. This API uses a callback to return the key information. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -199,7 +306,7 @@ Listens for a hard keyboard even. This API uses a callback to return the key inf | Name | Type | Mandatory| Description | | -------- | ------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| +| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| | callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.| @@ -207,8 +314,15 @@ Listens for a hard keyboard even. This API uses a callback to return the key inf **Example** ```js - KeyboardDelegate.on('keyDown', (event) => { - console.info('keyDown'); + KeyboardDelegate.on('keyUp', (keyEvent) => { + console.info('inputMethodEngine keyCode.(keyUp):' + JSON.stringify(keyEvent.keyCode)); + console.info('inputMethodEngine keyAction.(keyUp):' + JSON.stringify(keyEvent.keyAction)); + return true; + }); + KeyboardDelegate.on('keyDown', (keyEvent) => { + console.info('inputMethodEngine keyCode.(keyDown):' + JSON.stringify(keyEvent.keyCode)); + console.info('inputMethodEngine keyAction.(keyDown):' + JSON.stringify(keyEvent.keyAction)); + return true; }); ``` @@ -216,7 +330,7 @@ Listens for a hard keyboard even. This API uses a callback to return the key inf off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void -Cancels listening for a hard keyboard even. +Cancels listening for a hard keyboard even. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -224,20 +338,27 @@ Cancels listening for a hard keyboard even. | Name | Type | Mandatory| Description | | -------- | --------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| +| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| | callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. | **Example** ```js - KeyboardDelegate.off('keyDown'); + KeyboardDelegate.off('keyUp', (keyEvent) => { + console.log('delete keyUp notification.'); + return true; + }); + KeyboardDelegate.off('keyDown', (keyEvent) => { + console.log('delete keyDown notification.'); + return true; + }); ``` ### on('cursorContextChange') on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void -Listens for cursor context changes. This API uses a callback to return the cursor information. +Listens for cursor context changes. This API uses a callback to return the cursor information. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -253,18 +374,18 @@ Listens for cursor context changes. This API uses a callback to return the curso **Example** ```js - KeyboardDelegate.on('cursorContextChange', (x, y, height) => { - console.info('cursorContextChange'); + console.log('inputMethodEngine cursorContextChange x:' + x); + console.log('inputMethodEngine cursorContextChange y:' + y); + console.log('inputMethodEngine cursorContextChange height:' + height); }); - ``` ### off('cursorContextChange') off(type: 'cursorContextChange', callback?: (x: number, y:number, height:number) => void): void -Cancels listening for cursor context changes. +Cancels listening for cursor context changes. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -279,15 +400,15 @@ Cancels listening for cursor context changes. **Example** ```js - -KeyboardDelegate.off('cursorContextChange'); - +KeyboardDelegate.off('cursorContextChange', (x, y, height) => { + console.log('delete cursorContextChange notification.'); +}); ``` ### on('selectionChange') on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void -Listens for text selection changes. This API uses a callback to return the text selection information. +Listens for text selection changes. This API uses a callback to return the text selection information. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -301,18 +422,19 @@ Listens for text selection changes. This API uses a callback to return the text **Example** ```js - KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { - console.info('selectionChange'); + console.log('inputMethodEngine beforeEach selectionChange oldBegin:' + oldBegin); + console.log('inputMethodEngine beforeEach selectionChange oldEnd:' + oldEnd); + console.log('inputMethodEngine beforeEach selectionChange newBegin:' + newBegin); + console.log('inputMethodEngine beforeEach selectionChange newEnd:' + newEnd); }); - ``` ### off('selectionChange') off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void -Cancels listening for text selection changes. +Cancels listening for text selection changes. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -326,9 +448,9 @@ Cancels listening for text selection changes. **Example** ```js - -KeyboardDelegate.off('selectionChange'); - +KeyboardDelegate.off('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { + console.log('delete selectionChange notification.'); +}); ``` @@ -336,7 +458,7 @@ KeyboardDelegate.off('selectionChange'); on(type: 'textChange', callback: (text: string) => void): void -Listens for text changes. This API uses a callback to return the current text content. +Listens for text changes. This API uses a callback to return the current text content. This API requires two parameters, the first one being napi_string and the second one being napi_function. If either of these parameters is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -350,18 +472,16 @@ Listens for text changes. This API uses a callback to return the current text co **Example** ```js - KeyboardDelegate.on('textChange', (text) => { - console.info('textChange'); + console.log('inputMethodEngine textChange. text:' + text); }); - ``` ### off('textChange') off(type: 'textChange', callback?: (text: string) => void): void -Cancels listening for text changes. +Cancels listening for text changes. An exception is thrown in the following cases: (1) No parameter is passed; (2) Only one parameter is passed in, and it is not napi_string; (2) Two parameters are passed in, and the first parameter is not napi_string or the second parameter is not napi_function. If only one parameter is passed in, all listeners of the specified type will be canceled. If two parameters are passed in, the current listener of the specified type will be canceled. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -375,7 +495,9 @@ Cancels listening for text changes. **Example** ```js -KeyboardDelegate.off('textChange'); +keyboardDelegate.off('textChange', (text) => { + console.log('delete textChange notification. text:' + text); +}); ``` ## KeyboardController @@ -386,7 +508,7 @@ In the following API examples, you must first use [inputStart](#inputStart) to o hideKeyboard(callback: AsyncCallback<void>): void -Hides the keyboard. This API uses an asynchronous callback to return the result. +Hides the keyboard. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -400,28 +522,39 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ```js - KeyboardController.hideKeyboard(()=>{ - }); +KeyboardController.hideKeyboard((err) => { + if (err === undefined) { + console.error('hideKeyboard callback result---err: ' + err.msg); + return; + } + console.log('hideKeyboard callback.'); +}); ``` ### hideKeyboard hideKeyboard(): Promise<void> -Hides the keyboard. This API uses an asynchronous callback to return the result. +Hides the keyboard. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** -| Type | Description | -| ---------------- | -------- | -| Promise<void> | Promise used to return the result.| +| Type | Description | +| ---------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| **Example** ```js - KeyboardController.hideKeyboard(); +async function InputMethodEngine() { + await KeyboardController.hideKeyboard().then(() => { + console.info('hideKeyboard promise.'); + }).catch((err) => { + console.info('hideKeyboard promise err: ' + err.msg); + }); +} ``` ## TextInputClient @@ -432,7 +565,7 @@ In the following API examples, you must first use [inputStart](#inputStart) to o getForward(length:number, callback: AsyncCallback<string>): void -Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. +Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -446,16 +579,21 @@ Obtains the specific-length text before the cursor. This API uses an asynchronou **Example** ```js - TextInputClient.getForward(5,(text) =>{ - console.info("text = " + text); - }); + var length = 1; + TextInputClient.getForward(length, (err, text) => { + if (err === undefined) { + console.error('getForward callback result---err: ' + err.msg); + return; + } + console.log('getForward callback result---text: ' + text); + }); ``` ### getForward getForward(length:number): Promise<string> -Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. +Obtains the specific-length text before the cursor. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -474,15 +612,21 @@ Obtains the specific-length text before the cursor. This API uses an asynchronou **Example** ```js - var text = TextInputClient.getForward(5); - console.info("text = " + text); + async function InputMethodEngine() { + var length = 1; + await TextInputClient.getForward(length).then((text) => { + console.info('getForward promise result---res: ' + text); + }).catch((err) => { + console.error('getForward promise err: ' + err.msg); + }); + } ``` ### getBackward getBackward(length:number, callback: AsyncCallback<string>): void -Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. +Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -496,8 +640,13 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous **Example** ```js - TextInputClient.getBackward(5,(text)=>{ - console.info("text = " + text); + var length = 1; + TextInputClient.getBackward(length, (err, text) => { + if (err === undefined) { + console.error('getBackward callback result---err: ' + err.msg); + return; + } + console.log('getBackward callback result---text: ' + text); }); ``` @@ -505,7 +654,7 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous getBackward(length:number): Promise<string> -Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. +Obtains the specific-length text after the cursor. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -524,15 +673,21 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous **Example** ```js - var text = TextInputClient.getBackward(5); - console.info("text = " + text); + async function InputMethodEngine() { + var length = 1; + await TextInputClient.getBackward(length).then((text) => { + console.info('getBackward promise result---res: ' + text); + }).catch((err) => { + console.error('getBackward promise err: ' + err.msg); + }); + } ``` ### deleteForward deleteForward(length:number, callback: AsyncCallback<boolean>): void -Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. +Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -546,15 +701,24 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c **Example** ```js - TextInputClient.deleteForward(5,(isSuccess)=>{ - console.info("isSuccess = " + isSuccess); + var length = 1; + TextInputClient.deleteForward(length, (err, result) => { + if (err === undefined) { + console.error('deleteForward callback result---err: ' + err.msg); + return; + } + if (result) { + console.info('Success to deleteForward.(callback) '); + } else { + console.error('Failed to deleteForward.(callback) '); + } }); ``` ### deleteForward deleteForward(length:number): Promise<boolean> -Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. +Deletes the fixed-length text before the cursor. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -573,15 +737,25 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c **Example** ```js -var isSuccess = TextInputClient.deleteForward(5); - console.info("isSuccess = " + isSuccess); +async function InputMethodEngine() { + var length = 1; + await TextInputClient.deleteForward(length).then((result) => { + if (result) { + console.info('Success to deleteForward.(promise) '); + } else { + console.error('Failed to deleteForward.(promise) '); + } + }).catch((err) => { + console.error('deleteForward promise err: ' + err.msg); + }); +} ``` ### deleteBackward deleteBackward(length:number, callback: AsyncCallback<boolean>): void -Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. +Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -595,22 +769,30 @@ Deletes the fixed-length text after the cursor. This API uses an asynchronous ca **Example** ```js - - TextInputClient.deleteBackward(5, (isSuccess)=>{ - console.info("isSuccess = " + isSuccess); +var length = 1; +TextInputClient.deleteBackward(length, (err, result) => { + if (err === undefined) { + console.error('deleteBackward callback result---err: ' + err.msg); + return; + } + if (result) { + console.info('Success to deleteBackward.(callback) '); + } else { + console.error('Failed to deleteBackward.(callback) '); + } }); - ``` ### deleteBackward deleteBackward(length:number): Promise<boolean> -Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. +Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | length | number | Yes| Text length.| @@ -624,16 +806,24 @@ Deletes the fixed-length text after the cursor. This API uses an asynchronous ca **Example** ```js - - var isSuccess = TextInputClient.deleteBackward(5); - console.info("isSuccess = " + isSuccess); - +async function InputMethodEngine() { + var length = 1; + await TextInputClient.deleteBackward(length).then((result) => { + if (result) { + console.info('Success to deleteBackward.(promise) '); + } else { + console.error('Failed to deleteBackward.(promise) '); + } + }).catch((err) => { + console.error('deleteBackward promise err: ' + err.msg); + }); +} ``` ### sendKeyFunction sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void -Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. +Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -647,18 +837,24 @@ Sets the Enter key to send the text to its target. This API uses an asynchronous **Example** ```js - - TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{ - console.info("isSuccess = " + isSuccess); +TextInputClient.sendKeyFunction(keyFunction, (err, result) => { + if (err === undefined) { + console.error('sendKeyFunction callback result---err: ' + err.msg); + return; + } + if (result) { + console.info('Success to sendKeyFunction.(callback) '); + } else { + console.error('Failed to sendKeyFunction.(callback) '); + } }); - ``` ### sendKeyFunction sendKeyFunction(action:number): Promise<boolean> -Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. +Sets the Enter key to send the text to its target. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -677,15 +873,24 @@ Sets the Enter key to send the text to its target. This API uses an asynchronous **Example** ```js - var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT); - console.info("isSuccess = " + isSuccess); + async function InputMethodEngine() { + await client.sendKeyFunction(keyFunction).then((result) => { + if (result) { + console.info('Success to sendKeyFunction.(promise) '); + } else { + console.error('Failed to sendKeyFunction.(promise) '); + } + }).catch((err) => { + console.error('sendKeyFunction promise err:' + err.msg); + }); + } ``` ### insertText insertText(text:string, callback: AsyncCallback<boolean>): void -Inserts text. This API uses an asynchronous callback to return the result. +Inserts text. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -699,18 +904,24 @@ Inserts text. This API uses an asynchronous callback to return the result. **Example** ```js - -TextInputClient.insertText("test", (isSuccess)=>{ - console.info("isSuccess = " + isSuccess); +TextInputClient.insertText('test', (err, result) => { + if (err === undefined) { + console.error('insertText callback result---err: ' + err.msg); + return; + } + if (result) { + console.info('Success to insertText.(callback) '); + } else { + console.error('Failed to insertText.(callback) '); + } }); - ``` ### insertText insertText(text:string): Promise<boolean> -Inserts text. This API uses an asynchronous callback to return the result. +Inserts text. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -729,15 +940,24 @@ Inserts text. This API uses an asynchronous callback to return the result. **Example** ```js - var isSuccess = TextInputClient.insertText("test"); - console.info("isSuccess = " + isSuccess); + async function InputMethodEngine() { + await TextInputClient.insertText('test').then((result) => { + if (result) { + console.info('Success to insertText.(promise) '); + } else { + console.error('Failed to insertText.(promise) '); + } + }).catch((err) => { + console.error('insertText promise err: ' + err.msg); + }); + } ``` ### getEditorAttribute getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void -Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. +Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -750,15 +970,21 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to **Example** ```js - TextInputClient.getEditorAttribute((EditorAttribute)=>{ - }); + TextInputClient.getEditorAttribute((err, editorAttribute) => { + if (err === undefined) { + console.error('getEditorAttribute callback result---err: ' + err.msg); + return; + } + console.log('editorAttribute.inputPattern(callback): ' + JSON.stringify(editorAttribute.inputPattern)); + console.log('editorAttribute.enterKeyType(callback): ' + JSON.stringify(editorAttribute.enterKeyType)); + }); ``` ### getEditorAttribute -getEditorAttribute(): EditorAttribute +getEditorAttribute(): Promise<EditorAttribute> -Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. +Obtains the attribute of the edit box. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -766,14 +992,79 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<[EditorAttribute](#EditorAttribute)> | Promise used to return the attribute of the edit box. | +| Promise<[EditorAttribute](#EditorAttribute)> | Promise used to return the attribute of the edit box. | **Example** ```js - var EditorAttribute = TextInputClient.getEditorAttribute(); + async function InputMethodEngine() { + await TextInputClient.getEditorAttribute().then((editorAttribute) => { + console.info('editorAttribute.inputPattern(promise): ' + JSON.stringify(editorAttribute.inputPattern)); + console.info('editorAttribute.enterKeyType(promise): ' + JSON.stringify(editorAttribute.enterKeyType)); + }).catch((err) => { + console.error('getEditorAttribute promise err: ' + err.msg); + }); + } ``` +### moveCursor9+ + +moveCursor(direction: number, callback: AsyncCallback<void>): void + +Moves the cursor. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------------------------- | ---- | -------------- | +| direction | number | Yes | Direction in which the cursor moves.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +TextInputClient.moveCursor(inputMethodEngine.CURSOR_xxx, (err) => { + if (err === undefined) { + console.error('moveCursor callback result---err: ' + err.msg); + return; + } +}); +``` + +### moveCursor9+ + +moveCursor(direction: number): Promise<void> + +Moves the cursor. This API uses a promise to return the result. If the required parameter is not passed in, an exception is thrown. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | -------------- | +| direction | number | Yes | Direction in which the cursor moves.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + + ```js +async function InputMethodEngine() { + await TextInputClient.moveCursor(inputMethodEngine.CURSOR_xxx).then(async (err) => { + console.log('moveCursor success'); + }).catch((err) => { + console.error('moveCursor success err: ' + err.msg); + }); +} + ``` + ## EditorAttribute Describes the attribute of the edit box. 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 d2dcd1fdd0..245865cc40 100644 --- a/en/application-dev/reference/apis/js-apis-screen-lock.md +++ b/en/application-dev/reference/apis/js-apis-screen-lock.md @@ -233,61 +233,46 @@ Locks the screen. This API uses a promise to return the result. }); ``` +## EventType -## screenlock.on9+ - -on(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | 'unlockScreen' | 'beginExitAnimation', callback: Callback\): void - -Subscribes to screen lock status changes. +Defines the system event type. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type.
- **"beginWakeUp"**: Wakeup starts.
- **"endWakeUp"**: Wakeup ends.
- **"beginScreenOn"**: Screen turn-on starts.
- **"endScreenOn"**: Screen turn-on ends.
- **"beginScreenOff"**: Screen turn-off starts.
- **"endScreenOff"**: Screen turn-off ends.
- **"unlockScreen"**: The screen is unlocked.
- **"beginExitAnimation"**: Animation starts to exit.| -| callback | Callback\ | Yes| Callback used to return the result.| - -**Example** - - ```js - screenlock.on('beginWakeUp', () => { - console.log('beginWakeUp triggered'); - }); - ``` - -## screenlock.on9+ - -on(type: 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback\): void - -Subscribes to screen lock status changes. +| 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.| + + +## SystemEvent + +Defines the structure of the system event callback. **System capability**: SystemCapability.MiscServices.ScreenLock -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type.
- **"beginSleep"**: The screen enters sleep mode.
- **"endSleep"**: The screen exits sleep mode.
- **"changeUser"**: The user is switched.| -| callback | Callback\ | Yes| Callback used to return the result. | - -**Example** +| Name| Description| +| -------- | -------- | +| eventType | System event type.| +| params | System event parameters.| - ```js - screenlock.on('beginSleep', (why) => { - console.log('beginSleep triggered:' + why); - }); - ``` -## screenlock.on9+ +## screenlock.onSystemEvent9+ -on(type: 'screenlockEnabled', callback: Callback\): void +onSystemEvent(callback: Callback\): boolean -Subscribes to screen lock status changes. +Registers a callback for system events related to screen locking. **System capability**: SystemCapability.MiscServices.ScreenLock @@ -297,41 +282,26 @@ Subscribes to screen lock status changes. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes| Event type.
- **"screenlockEnabled"**: Screen lock is enabled.| -| callback | Callback\ | Yes| Callback used to return the result. | - -**Example** - - ```js - screenlock.on('screenlockEnabled', (isEnabled) => { - console.log('screenlockEnabled triggered, result:' + isEnabled); - }); - ``` - -## screenlock.off9+ +| callback | Callback\ | Yes| Callback for system events related to screen locking| -off(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' - | 'unlockScreen' | 'beginExitAnimation' | 'screenlockEnabled' | 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback\): void - -Unsubscribes from screen lock status changes. - -**System capability**: SystemCapability.MiscServices.ScreenLock - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** +**Return value** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type.
- **"beginWakeUp"**: Wakeup starts.
- **"endWakeUp"**: Wakeup ends.
- **"beginScreenOn"**: Screen turn-on starts.
- **"endScreenOn"**: Screen turn-on ends.
- **"beginScreenOff"**: Screen turn-off starts.
- **"endScreenOff"**: Screen turn-off ends.
- **"unlockScreen"**: The screen is unlocked.
- **"beginExitAnimation"**: Animation starts to exit.
- **"screenlockEnabled"**: Screen lock is enabled.
- **"beginSleep"**: The screen enters sleep mode.
- **"endSleep"**: The screen exits sleep mode.
- **"changeUser"**: The user is switched.| -| callback | Callback\ | Yes| Callback used to return the result.| +| Type | Description | +| ------- | -------------------------------------------- | +| boolean | The value **true** means that the callback is registered successfully, and **false** means the opposite.| **Example** ```js - screenlock.off('beginWakeUp', () => { - console.log("callback"); - }); + 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`) + } ``` ## screenlock.sendScreenLockEvent9+ @@ -375,7 +345,7 @@ Sends an event to the screen lock service. This API uses a promise to return the | 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.| +| parameter | number | Yes| Screen unlock status.
- **0**: The unlock is successful.
- **1**: The unlock fails.
- **2**: The unlock is canceled.| **Return value** -- GitLab