diff --git a/en/application-dev/reference/apis/js-apis-inputmethod-InputMethodCommon.md b/en/application-dev/reference/apis/js-apis-inputmethod-InputMethodCommon.md new file mode 100644 index 0000000000000000000000000000000000000000..ed0c80507f40597592206e195dd6780de7133401 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inputmethod-InputMethodCommon.md @@ -0,0 +1,41 @@ +# InputMethodCommon + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +The **InputMethodCommon** module provides the common attributes defined by the input method framework. + +## Direction + +Enumerates the directions of cursor movement. + + **System capability**: SystemCapability.MiscServices.InputMethodFramework + +| Name | Value | Description | +| ------------ | ---- | ---------- | +| CURSOR_UP | 1 | The cursor moves upward.| +| CURSOR_DOWN | 2 | The cursor moves downward.| +| CURSOR_LEFT | 3 | The caret moves leftward.| +| CURSOR_RIGHT | 4 | The caret moves rightward.| + +## Range + +Describes the range of the selected text. + + **System capability**: SystemCapability.MiscServices.InputMethodFramework + +| Name | Type | Readable| Writable| Description | +| ----- | ------ | ---- | ---- | ---------------------------------- | +| start | number | Yes | Yes | Index of the first selected character in the text box.| +| end | number | Yes | Yes | Index of the last selected character in the text box.| + +## Movement + +Describes the direction in which the cursor moves when the text is selected. + + **System capability**: SystemCapability.MiscServices.InputMethodFramework + +| Name | Type | Readable| Writable| Description | +| --------- | ----------------------- | ---- | ---- | ---------------------------------- | +| direction | [Direction](#direction) | Yes | Yes | Direction in which the cursor moves when the text is selected.| diff --git a/en/application-dev/reference/apis/js-apis-inputmethod.md b/en/application-dev/reference/apis/js-apis-inputmethod.md index bdc166cd9d3b5a60636214b72311a2c8368c8d6d..be7f5edb92e6b7345a69551ce269fa197c524f24 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod.md @@ -839,6 +839,92 @@ inputMethodController.stopInput().then((result) => { }) ``` +### on('selectByRange')10+ + +on(type: 'selectByRange', callback: Callback<Range>): void + +Enables listening for the selection-by-range event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **selectByRange** indicates the selection-by-range event.| +| callback | Callback<[Range](./js-apis-inputmethod-InputMethodCommon.md#range)> | Yes | Callback used to return the range of the text to be selected.
Your application needs to select the text in the returned range in the text box.| + +**Example** + +```js +inputMethodController.on('selectByRange', (range) => { + console.info('Succeeded in subscribing selectByRange: start: ' + range.start + " , end: " + range.end); +}); +``` + +### off('selectByRange')10+ + +off(type: 'selectByRange'): void + +Disables listening for the selection-by-range event. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **selectByRange** indicates the selection-by-range event.| + +**Example** + +```js +inputMethodController.off('selectByRange'); +``` + +### on('selectByMovement')10+ + +on(type: 'selectByMovement', callback: Callback<Range>): void + +Enables listening for the selection-by-cursor-movement event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **selectByMovement** indicates the selection-by-cursor-movement event.| +| callback | Callback<[Movement](./js-apis-inputmethod-InputMethodCommon.md#movement)> | Yes | Callback used to return the range of the text to be selected.
Your application needs to select the text in the returned range in the text box.| + +**Example** + +```js +inputMethodController.on('selectByMovement', (movement) => { + console.info('Succeeded in subscribing selectByMovement: direction: ' + movement.direction); +}); +``` + +### off('selectByMovement')10+ + +off(type: 'selectByMovement'): void + +Disables listening for the selection-by-cursor-movement event. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **selectByMovement** indicates the selection-by-cursor-movement event.| + +**Example** + +```js +inputMethodController.off('selectByMovement'); +``` + ## InputMethodSetting8+ 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. diff --git a/en/application-dev/reference/apis/js-apis-inputmethodengine.md b/en/application-dev/reference/apis/js-apis-inputmethodengine.md index 7cfb76e570ae3faf57fdf3ff31cd6cbcb9103eae..fd98e98d1f748ef094d7dd096033fc0459e8ac8b 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethodengine.md +++ b/en/application-dev/reference/apis/js-apis-inputmethodengine.md @@ -1495,6 +1495,241 @@ try { } ``` +### selectByRange10+ + +selectByRange(range: Range, callback: AsyncCallback<void>): void + +Selects text based on the specified range. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| range | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | Yes | Range of the selected text. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the selection event is sent, **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). + +| Error Code ID| Error Message | +| -------- | -------------------------- | +| 401 | parameter error. | +| 12800003 | Input method client error. | + +**Example** + +```js +try { + inputClient.selectByRange({start: 0, end: 1}, (err) => { + if (err !== undefined) { + console.error('Failed to selectByRange: ${err.message}'); + return; + } + console.info('Succeeded in selecting by range.'); + }); +} catch (err) { + console.error('Failed to selectByRange: ${err.message}'); +} +``` + +### selectByRange10+ + +selectByRange(range: Range): Promise<void> + +Selects text based on the specified range. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------------- | ---- | ---------------- | +| range | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | Yes | Range of the selected text.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | -------------------------- | +| 401 | parameter error. | +| 12800003 | Input method client error. | + +**Example** + +```js +try { + inputClient.selectByRange({start: 0, end:1}).then(() => { + console.log('Succeeded in selecting by range.'); + }).catch((err) => { + console.error('Failed to selectByRange: ${err.message}'); + }); +} catch (err) { + console.log('Failed to selectByRange: ${err.message}'); +} +``` + +### selectByMovement10+ + +selectByMovement(movement: Movement, callback: AsyncCallback<void>): void + +Selects text based on the cursor movement direction. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | Yes | Direction in which the cursor moves when the text is selected. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the selection event is sent, **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). + +| Error Code ID| Error Message | +| -------- | -------------------------- | +| 401 | parameter error. | +| 12800003 | Input method client error. | + +**Example** + +```js +try { + inputClient.selectByMovement({direction: 1}, (err) => { + if (err !== undefined) { + console.error('Failed to selectByMovement: ${err.message}'); + return; + } + console.info('Succeeded in selecting by movement.'); + }); +} catch (err) { + console.error('Failed to selectByMovement: ${err.message}'); +} +``` + +### selectByMovement10+ + +selectByMovement(range: Range): Promise<void> + +Selects text based on the specified range. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ---------------------- | +| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | Yes | Direction in which the cursor moves when the text is selected.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | -------------------------- | +| 401 | parameter error. | +| 12800003 | Input method client error. | + +**Example** + +```js +try { + inputClient.selectByMovement({direction: 1}).then(() => { + console.log('Succeeded in selecting by movement.'); + }).catch((err) => { + console.error('Failed to selectByMovement: ${err.message}'); + }); +} catch (err) { + console.log('Failed to selectByMovement: ${err.message}'); +} +``` + +### getTextIndexAtCursor10+ + +getTextIndexAtCursor(callback: AsyncCallback<number>): void + +Obtains the index of the text where the cursor is located. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the text index is obtained, **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). + +| Error Code ID| Error Message | +| -------- | ------------------------------ | +| 401 | parameter error. | +| 12800003 | Input method client error. | +| 12800006 | Input method controller error. | + +**Example** + +```js +inputClient.getTextIndexAtCursor((err, index) => { + if (err !== undefined) { + console.error('Failed to getTextIndexAtCursor: ${err.message}'); + return; + } + console.info('Succeeded in getTextIndexAtCursor: ' + index); +}); +``` + +### getTextIndexAtCursor10+ + +getTextIndexAtCursor(): Promise<number> + +Obtains the index of the text where the cursor is located. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Return value** + +| Type | Description | +| --------------------- | --------------------------------------- | +| Promise<number> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | ------------------------------ | +| 12800003 | Input method client error. | +| 12800006 | Input method controller error. | + +**Example** + +```js +inputClient.getTextIndexAtCursor().then((index) => { + console.info('Succeeded in getTextIndexAtCursor: ' + index); +}).catch((err) => { + console.error('Failed to getTextIndexAtCursor: ${err.message}'); +}); +``` + ## EditorAttribute Attribute of the edit box.