The **inputMethodSubtype** module provides APIs for managing the attributes of input method subtypes. Different attribute settings result in different subtypes.
> **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.
## Modules to Import
```
import inputMethodEngine from '@ohos.inputMethodSubtype';
The **inputMethod** module provides an input method framework, which can be used to hide the keyboard, obtain the list of installed input methods, display the dialog box for input method selection, and more.
The **inputMethod** module provides an input method framework, which can be used to hide the keyboard, obtain the list of installed input methods, display the dialog box for input method selection, and more.
...
@@ -9,20 +9,19 @@ The **inputMethod** module provides an input method framework, which can be used
...
@@ -9,20 +9,19 @@ The **inputMethod** module provides an input method framework, which can be used
| name<sup>9+</sup> | string | Yes| No| Internal name of the input method. Mandatory.|
| methodId | string | Yes| No| Ability name.|
| id<sup>9+</sup> | string | Yes| No| Unique ID of the input method. Mandatory.|
| label<sup>9+</sup> | string | Yes| No| External display name of the input method. Optional.|
| icon<sup>9+</sup> | string | Yes| No| Icon of the input method. Optional.|
| iconId<sup>9+</sup> | number | Yes| No| Icon ID of the input method. Optional.|
| extra<sup>9+</sup> | object | Yes| Yes| Extra information about the input method. Mandatory.|
| packageName<sup>(deprecated)</sup> | string | Yes| No| Name of the input method package. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **name**.|
| methodId<sup>(deprecated)</sup> | string | Yes| No| Unique ID of the input method. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **id**.|
## inputMethod.getInputMethodController
## inputMethod.getController<sup>9+</sup>
getInputMethodController(): InputMethodController
getController(): InputMethodController
Obtains an **[InputMethodController](#inputmethodcontroller)** instance.
Obtains an **[InputMethodController](#inputmethodcontroller)** instance.
...
@@ -49,15 +54,23 @@ Obtains an **[InputMethodController](#inputmethodcontroller)** instance.
...
@@ -49,15 +54,23 @@ Obtains an **[InputMethodController](#inputmethodcontroller)** instance.
Switches to another input method. This API can be used only in the stage model. It uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown.
Switches to another input method. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
| callback | AsyncCallback<boolean> | Yes| Callback used to return the execution result.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
Switches to another input method. This API can be used only in the stage model. It uses a promise to return the result. If the required parameter is not passed in, an exception is thrown.
Switches to another input method. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.|
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
In the following API examples, you must first use **[getInputMethodController](#inputmethodgetinputmethodcontroller)** to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance.
In the following API examples, you must first use [getController](#inputmethodgetcontroller9) to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance.
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.
Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses an asynchronous callback to return the result.
@@ -176,29 +557,42 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
...
@@ -176,29 +557,42 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the keyboard is successfully hidden.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
console.error('failed to stopInput because: '+JSON.stringify(error));
if(error!==undefined){
console.error('Failed to stopInputSession: '+JSON.stringify(error));
return;
return;
}
}
if(result){
if(result){
console.info('Success to stopInput.(callback)');
console.info('Succeeded in stopping inputSession.');
}else{
}else{
console.error('Failed to stopInput.(callback)');
console.error('Failed to stopInputSession.');
}
}
});
});
}catch(error){
console.error('Failed to stopInputSession: '+JSON.stringify(error));
}
```
```
### stopInput
### stopInputSession<sup>9+</sup>
stopInput(): Promise<boolean>
stopInputSession(): Promise<boolean>
Hides the keyboard. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown.
Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses a promise to return the result.
@@ -206,28 +600,42 @@ Hides the keyboard. This API uses a promise to return the result. If any paramet
...
@@ -206,28 +600,42 @@ Hides the keyboard. This API uses a promise to return the result. If any paramet
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<boolean> | Promise used to return whether the keyboard is successfully hidden.|
| Promise<boolean> | Promise used to return the result. The value **true** means that the ending is successful, and **false** means the opposite.|
**Example**
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
Shows this soft keyboard. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown.
Shows this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| 12800008 | Input method manager service error. |
**Example**
**Example**
```js
```js
InputMethodController.showSoftKeyboard((err)=>{
inputMethodController.showSoftKeyboard((err)=>{
if(err===undefined){
if(err===undefined){
console.info('showSoftKeyboard success');
console.info('Succeeded in showing softKeyboard.');
}else{
}else{
console.error('showSoftKeyboard failed because : '+JSON.stringify(err));
console.error('Failed to showSoftKeyboard: '+JSON.stringify(err));
}
}
})
})
```
```
### showSoftKeyboard<sup>9+</sup>
### showSoftKeyboard<sup>9+</sup> ###
showSoftKeyboard(): Promise<void>
showSoftKeyboard(): Promise<void>
Shows this soft keyboard. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown.
Shows this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
Hides this soft keyboard. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown.
Hides this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| 12800008 | Input method manager service error. |
**Example**
**Example**
```js
```js
InputMethodController.hideSoftKeyboard((err)=>{
inputMethodController.hideSoftKeyboard((err)=>{
if(err===undefined){
if(err===undefined){
console.info('hideSoftKeyboard success');
console.info('Succeeded in hiding softKeyboard.');
}else{
}else{
console.error('hideSoftKeyboard failed because : '+JSON.stringify(err));
console.error('Failed to hideSoftKeyboard: '+JSON.stringify(err));
}
}
})
})
```
```
### hideSoftKeyboard<sup>9+</sup>
### hideSoftKeyboard<sup>9+</sup> ###
hideSoftKeyboard(): Promise<void>
hideSoftKeyboard(): Promise<void>
Hides this soft keyboard. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown.
Hides this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9).
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Example**
```js
inputMethodController.stopInput((error,result)=>{
if(error!==undefined){
console.error('Failed to stopInput: '+JSON.stringify(error));
return;
}
if(result){
console.info('Succeeded in stopping input.');
}else{
console.error('Failed to stopInput.');
}
});
```
### stopInput<sup>(deprecated)</sup>
stopInput(): Promise<boolean>
Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9).
| Promise<boolean> | Promise used to return the result. The value **true** means that the hiding is successful, and **false** means the opposite.|
In the following API examples, you must first use **[getInputMethodSetting](#inputmethodgetinputmethodcontroller)** to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance.
In the following API examples, you must first use [getSetting](#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance.
Obtains a list of activated or deactivated input methods. This API uses an asynchronous callback to return the result. If the required two parameters are not passed in, an exception is thrown.
Obtains all subtypes of a specified input method. This API uses an asynchronous callback to return the result.
| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.|
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes| Callback used to return all subtypes of the specified input method.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the specified input method.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes | Callback used to return all subtypes of the current input method.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the current input method.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
Obtains a list of activated or deactivated input methods. In the current version, an activated input method is the input method in use, and a deactivated one is any of the installed input methods except the one in use. This API uses an asynchronous callback to return the result.
| 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. |
| 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 | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return a list of activated or deactivated input methods.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
Obtains a list of activated or deactivated input methods. This API uses a promise to return the result. If any parameter is passed in, an exception is thrown.
Obtains a list of activated or deactivated input methods. In the current version, an activated input method is the input method in use, and a deactivated one is any of the installed input methods except the one in use. This API uses a promise to return the result.
| 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.|
| 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.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
Obtains a list of installed input methods. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown.
Obtains a list of installed input methods. 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 [getInputMethods](#getinputmethods9).
| callback | Array<[InputMethodProperty](#inputmethodproperty8)> | Yes | Callback used to return the list of installed input methods.|
| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return the list of installed input methods.|
Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. If the required parameter is not passed in, an exception is thrown.
Displays a dialog box for selecting an input method. 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 [showOptionalInputMethods()](#showoptionalinputmethods9).
@@ -448,27 +1291,31 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono
...
@@ -448,27 +1291,31 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
Displays a dialog box for selecting an input method. This API uses a promise to return the result.
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.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [showOptionalInputMethods()](#showoptionalinputmethods9-1).
The **inputMethodEngine** module streamlines the interaction between applications and input methods. By calling APIs of this module, applications can accept text input through the input methods, be bound to input method services, request the keyboard to display or hide, listen for the input method status, and much more.
The **inputMethodEngine** module streamlines the interaction between input methods and applications. By calling APIs of this module, applications can be bound to input method services to accept text input through the input methods, request the keyboard to display or hide, listen for the input method status, and much more.
> **NOTE**
> **NOTE**
>
>
>The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
## Modules to Import
...
@@ -12,95 +12,143 @@ The **inputMethodEngine** module streamlines the interaction between application
...
@@ -12,95 +12,143 @@ The **inputMethodEngine** module streamlines the interaction between application
import inputMethodEngine from '@ohos.inputmethodengine';
import inputMethodEngine from '@ohos.inputmethodengine';
```
```
## inputMethodEngine
## Constants
Provides the constants.
Provides the constant values of function keys, edit boxes, and the cursor.
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethodAbility()](#inputmethodenginegetinputmethodability9).
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getKeyboardDelegate()](#inputmethodenginegetkeyboarddelegate9).
In the following API examples, you must first use [getInputMethodEngine](#getInputMethodEngine) to obtain an **InputMethodEngine** instance, and then call the APIs using the obtained instance.
In the following API examples, you must first use **[getInputMethodEngine](#inputmethodenginegetinputmethodenginedeprecated)** to obtain an **InputMethodEngine** instance, and then call the APIs using the obtained instance.
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.
Enables listening for the input method binding event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.|
| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.|
| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | Yes| Callback used to return the result.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | Yes| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
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.
Cancels listening for the input method binding event.
| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.|
| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.|
| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | No| Callback used to return the result.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | No| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event. |
| callback | () => void | Yes | Callback used to return the result. |
| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.|
| callback | () => void | No | Callback used to return the result.|
In the following API examples, you must first use **[getInputMethodAbility](#inputmethodenginegetinputmethodability9)** to obtain an **InputMethodAbility** instance, and then call the APIs using the obtained instance.
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.
Enables listening for a keyboard event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>- The value **'keyboardShow'**means to listen for displaying of the keyboard.<br>- The value **'keyboardHide'** means to listen for hiding of the keyboard. |
| type | string | Yes | Listening type.<br>- The value **'keyboardShow'**indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.|
| callback | void | No | Callback used to return the result. |
| callback | () => void | Yes | Callback used to return the result. |
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.
Disables listening for a keyboard event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** means to listen for displaying of the keyboard.<br>- The value **'keyboardHide'** means to listen for hiding of the keyboard.|
| type | string | Yes | Listening type.<br>The value **'keyboardShow'** indicates the keyboard display event.<br>The value **'keyboardHide'** indicates the keyboard hiding event.|
| callback | void | No | Callback used to return the result. |
| callback | () => void | No | Callback used to return the result. |
In the following API examples, you must first use [createKeyboardDelegate](#createKeyboardDelegate) to obtain a **KeyboardDelegate** instance, and then call the APIs using the obtained instance.
Disables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>The value **'setSubtype'** indicates the input method subtype setting event.|
| callback | (inputMethodSubtype: [InputMethodSubtype](js-apis-inputmethod-subtype.md)) => void | No | Callback used to return the input method subtype. |
In the following API examples, you must first use **[getKeyboardDelegate](#inputmethodenginegetkeyboarddelegate9)** to obtain a **KeyboardDelegate** instance, and then call the APIs using the obtained instance.
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.
Enables listening for a keyboard event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.|
| type | string | Yes | Listening type.<br>The value **'keyDown'** indicates the keydown event.<br>The value **'keyUp'** indicates the keyup event.|
| callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.|
| callback | (event: [KeyEvent](#keyevent)) => boolean | Yes| Callback used to return the key information.|
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.
Disables listening for a keyboard event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.|
| type | string | Yes | Listening type.<br>The value **'keyDown'** indicates the keydown event.<br>The value **'keyUp'** indicates the keyup event.|
| callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. |
| callback | (event: [KeyEvent](#keyevent)) => boolean | No | Callback used to return the key 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.
Enables listening for the cursor change event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.|
| type | string | Yes | Listening type.<br>The value **'cursorContextChange'** indicates the cursor change event.|
| callback | number | Yes | Callback used to return the cursor information. |
| callback | (x: number, y: number, height: number) => void | Yes | Callback used to return the cursor information.<br>- **x**: x coordinate of the top of the cursor.<br>- **y**: x coordinate of the bottom of the cursor.<br>- **height**: height of the cursor.|
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.
Cancels listening for cursor context changes. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.|
| type | string | Yes | Listening type.<br>The value **'cursorContextChange'** indicates the cursor change event.|
| callback | number | No | Callback used to return the cursor information. |
| callback | (x: number, y:number, height:number) => void | No | Callback used to return the cursor information.<br>- **x**: x coordinate of the top of the cursor.<br>- **y**: x coordinate of the bottom of the cursor.<br>- **height**: height of the cursor.<br>|
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.
Enables listening for the text selection change event. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.|
| type | string | Yes | Listening type.<br>The value **'selectionChange'** indicates the text selection change event.|
| callback | number | Yes | Callback used to return the text selection information. |
| callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | Yes | Callback used to return the text selection information.<br>- **oldBegin**: start of the selected text before the change.<br>- **oldEnd**: end of the selected text before the change.<br>- **newBegin**: start of the selected text after the change.<br>- **newEnd**: end of the selected text after the change.|
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.
Cancels listening for text selection changes. This API uses an asynchronous callback to return the result.
| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.|
| type | string | Yes | Listening type.<br>The value **'selectionChange'** indicates the text selection change event.|
| callback | number | No | Callback used to return the text selection information. |
| callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | No | Callback used to return the text selection information.<br>- **oldBegin**: start of the selected text before the change.<br>- **oldEnd**: end of the selected text before the change.<br>- **newBegin**: start of the selected text after the change.<br>- **newEnd**: end of the selected text after the change.<br>|
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.
Enables listening for the text change event. This API uses an asynchronous callback to return the result.
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.
Cancels listening for text changes. This API uses an asynchronous callback to return the result.
In the following API examples, you must first use [inputStart](#inputStart) to obtain a **KeyboardController** instance, and then call the APIs using the obtained instance.
In the following API examples, you must first use **[on('inputStart')](#oninputstart9)** to obtain a **KeyboardController** instance, and then call the APIs using the obtained instance.
| callback | AsyncCallback<void> | No | Callback used to return the result.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
In the following API examples, you must first use [inputStart](#inputStart) to obtain a **TextInputClient** instance, and then call the APIs using the obtained instance.
Hides the keyboard. 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.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [hide](#hide9).
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
| callback | AsyncCallback<string> | Yes| Callback used to return the text.|
**Example**
**Example**
```js
```js
varlength=1;
keyboardController.hideKeyboard((err)=>{
TextInputClient.getForward(length,(err,text)=>{
if(err!==undefined){
if(err===undefined){
console.error('Failed to hide Keyboard: '+JSON.stringify(err));
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.
In the following API examples, you must first use **[on('inputStart')](#oninputstart9)** to obtain an **InputClient** instance, and then call the APIs using the obtained instance.
| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result.
@@ -635,26 +920,39 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous
...
@@ -635,26 +920,39 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| length | number | Yes| Text length.|
| callback | AsyncCallback<string> | Yes| Callback used to return the text.|
| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
console.log('Succeeded in getting forward, text: '+text);
});
});
```
}catch(err){
console.error('Failed to getForward: '+JSON.stringify(err));
}
```
### getBackward
### getForward<sup>9+</sup>
getBackward(length:number): Promise<string>
getForward(length:number): Promise<string>
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.
Obtains the specific-length text before the cursor. This API uses a promise 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.
Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result.
@@ -696,165 +1005,221 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c
...
@@ -696,165 +1005,221 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| length | number | Yes| Text length.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
getBackward(length:number): Promise<string>
Obtains the specific-length text after the cursor. This API uses a promise 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.
Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Example**
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
Deletes the fixed-length text before the cursor. This API uses a promise to return the result.
| Promise<boolean> | Promise used to return the result. |
| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Example**
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result.
| Promise<boolean> | Promise used to return the result. |
| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
@@ -899,29 +1272,38 @@ Inserts text. This API uses an asynchronous callback to return the result. If th
...
@@ -899,29 +1272,38 @@ Inserts text. This API uses an asynchronous callback to return the result. If th
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
| text | string | Yes| Text to insert.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| Promise<boolean> | Promise used to return the result. |
| Promise<boolean> | Promise used to return the result. The value **true** means that the insertion is successful, and **false** means the opposite. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
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.
Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<[EditorAttribute](#EditorAttribute)> | Yes| Attribute of the edit box. |
| callback | AsyncCallback<[EditorAttribute](#editorattribute)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the attribute of the edit box. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| direction | number | Yes | Direction in which the cursor moves.|
| direction | number | Yes | Direction in which the cursor moves.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [InputClient](#inputclient9).
In the following API examples, you must first use **[on('inputStart')](#oninputstart)** to obtain a **TextInputClient** instance, and then call the APIs using the obtained instance.
| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.|
**Example**
```js
letlength=1;
textInputClient.getForward(length,(err,text)=>{
if(err!==undefined){
console.error('Failed to getForward: '+JSON.stringify(err));
return;
}
console.log('Succeeded in getting forward, text: '+text);
});
```
### getForward<sup>(deprecated)</sup>
getForward(length:number): Promise<string>
Obtains the specific-length text before the cursor. 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 [getForward](#getforward9).
| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.|
**Example**
```js
letlength=1;
textInputClient.getBackward(length,(err,text)=>{
if(err!==undefined){
console.error('Failed to getBackward: '+JSON.stringify(err));
return;
}
console.log('Succeeded in getting borward, text: '+text);
});
```
### getBackward<sup>(deprecated)</sup>
getBackward(length:number): Promise<string>
Obtains the specific-length text after the cursor. 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 [getBackward](#getbackward9).
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.|
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.|
| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
| Promise<boolean> | Promise used to return the result. The value **true** means that the setting is successful, and **false** means the opposite.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Example**
```js
textInputClient.insertText('test',(err,result)=>{
if(err!==undefined){
console.error('Failed to insertText: '+JSON.stringify(err));
return;
}
if(result){
console.info('Succeeded in inserting text. ');
}else{
console.error('Failed to insertText. ');
}
});
```
### insertText<sup>(deprecated)</sup>
insertText(text:string): Promise<boolean>
Inserts text. 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 [insertText](#inserttext9).
| Promise<boolean> | Promise used to return the result. The value **true** means that the insertion is successful, and **false** means the opposite.|
| callback | AsyncCallback<[EditorAttribute](#editorattribute)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the attribute of the edit box. Otherwise, **err** is an error object.|
| value | number | No| Current progress.<br>Default value: **0**|
| value | number | No| Current progress.<br>Default value: **0**|
| min | number | No| Minimum value.<br>Default value: **0**|
| min | number | No| Minimum value.<br>Default value: **0**|
| max | number | No| Maximum value.<br>Default value: **100**|
| max | number | No| Maximum value.<br>Default value: **100**|
| step | number | No| Step of the slider.<br>Default value: **1**|
| step | number | No| Step of the slider.<br>Default value: **1**<br>Value range: [0.01, max]|
| style | SliderStyle | No| Style of the slider thumb and track.<br>Default value: **SliderStyle.OutSet**|
| style | SliderStyle | No| Style of the slider thumb and track.<br>Default value: **SliderStyle.OutSet**|
| direction<sup>8+</sup> | [Axis](ts-appendix-enums.md#axis) | No| Whether the slider moves horizontally or vertically.<br>Default value: **Axis.Horizontal**|
| direction<sup>8+</sup> | [Axis](ts-appendix-enums.md#axis) | No| Whether the slider moves horizontally or vertically.<br>Default value: **Axis.Horizontal**|
| reverse<sup>8+</sup> | boolean | No| Whether the slider values are reversed. By default, the values increase from left to right for a horizontal slider and from top to bottom for a vertical slider.<br>Default value: **false**|
| reverse<sup>8+</sup> | boolean | No| Whether the slider values are reversed. By default, the values increase from left to right for a horizontal slider and from top to bottom for a vertical slider.<br>Default value: **false**|
...
@@ -46,7 +46,7 @@ Except touch target attributes, the universal attributes are supported.
...
@@ -46,7 +46,7 @@ Except touch target attributes, the universal attributes are supported.
| trackColor | [ResourceColor](ts-types.md#resourcecolor) | Background color of the slider.|
| trackColor | [ResourceColor](ts-types.md#resourcecolor) | Background color of the slider.|
| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the selected part of the slider track.|
| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the selected part of the slider track.|
| showSteps | boolean | Whether to display the current step.<br>Default value: **false**|
| showSteps | boolean | Whether to display the current step.<br>Default value: **false**|
| showTips | boolean | Whether to display a bubble to indicate the percentage when the user drags the slider.<br>Default value: **false**|
| showTips | boolean | Whether to display a bubble to indicate the percentage when the user drags the slider.<br>Default value: **false**|
| trackThickness | [Length](ts-types.md#length) | Track thickness of the slider.|
| trackThickness | [Length](ts-types.md#length) | Track thickness of the slider.|
