1# Input Method Framework ChangeLog
2
3## cl.inputmethod_frameworks.1 API Error Information Return Method Change
4
5The internal APIs of the following modules used service logic return values to indicate error information, which did not comply with the error code specifications of OpenHarmony. Therefore, they are modified in API version 9 and later.
6
7 - Input method framework module: system API, @ohos.inputmethod.d.ts
8
9 - Input method service module: system API, @ohos.inputmethodengine.d.ts
10
11 - Input method ExtentionAbility module: system API, @ohos.inputmethodextensionability.d.ts
12
13 - Input method ExtentionContext module: system API, @ohos.inputmethodextensioncontext.d.ts
14
15 - Input method subtype module: system API, @ohos.inputMethodSubtype.d.ts
16
17Asynchronous API: An error message is returned via **AsyncCallback** or the **error** object of **Promise**.
18
19Synchronous API: An error message is returned via an exception.
20
21**Change Impacts**
22
23The application developed based on earlier versions needs to adapt the method for returning API error information. Otherwise, the original service logic will be affected.
24
25**Key API/Component Changes**
26
27Error code processing is added for the following APIs:
28  - getSetting(): InputMethodSetting;
29  - getController(): InputMethodController;
30  - switchInputMethod(target: InputMethodProperty, callback: AsyncCallback<boolean>): void;
31  - switchInputMethod(target: InputMethodProperty): Promise<boolean>;
32  - switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback<boolean>): void;
33  - switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise<boolean>;
34  - switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback<boolean>): void;
35  - switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean>;
36  - listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void;
37  - listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>>;
38  - listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void;
39  - listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>>;
40  - getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
41  - getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
42  - showOptionalInputMethods(callback: AsyncCallback<boolean>): void;
43  - showOptionalInputMethods(): Promise<boolean>;
44  - stopInputSession(callback: AsyncCallback<boolean>): void;
45  - stopInputSession(): Promise<boolean>;
46  - showSoftKeyboard(callback: AsyncCallback<void>): void;
47  - showSoftKeyboard():Promise<void>;
48  - hideSoftKeyboard(callback: AsyncCallback<void>): void;
49  - hideSoftKeyboard():Promise<void>;
50  - hide(callback: AsyncCallback<void>): void;
51  - hide(): Promise<void>;
52  - onCreate(want: Want): void;
53  - onDestroy(): void;
54    In **InputClient**:
55  - sendKeyFunction(action: number, callback: AsyncCallback<boolean>): void;
56  - sendKeyFunction(action: number): Promise<boolean>;
57  - deleteForward(length: number, callback: AsyncCallback<boolean>): void;
58  - deleteForward(length: number): Promise<boolean>;
59  - deleteBackward(length: number, callback: AsyncCallback<boolean>): void;
60  - deleteBackward(length: number): Promise<boolean>;
61  - insertText(text: string, callback: AsyncCallback<boolean>): void;
62  - insertText(text: string): Promise<boolean>;
63  - getForward(length: number, callback: AsyncCallback<string>): void;
64  - getForward(length: number): Promise<string>;
65  - getBackward(length: number, callback: AsyncCallback<string>): void;
66  - getBackward(length: number): Promise<string>;
67  - getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void;
68  - getEditorAttribute(): Promise<EditorAttribute>;
69  - moveCursor(direction: number, callback: AsyncCallback<void>): void;
70  - moveCursor(direction: number): Promise<void>;
71    In **InputMethodExtensionAbility**:
72  - onCreate(want: Want): void;
73  - onDestroy(): void;
74
75**Adaptation Guide**
76
77The following uses **showOptionalInputMethods** as an example for asynchronous APIs:
78
79Callback mode:
80
81```js
82import inputMethod from '@ohos.inputmethod';
83let inputMethodSetting = inputMethod.getSetting();
84try {
85    inputMethodSetting.showOptionalInputMethods((err, data) => {
86        if (err !== undefined) {
87            console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
88            return;
89        }
90        console.info('Succeeded in showing optionalInputMethods.');
91    });
92} catch (err) {
93    console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
94}
95```
96
97Promise mode:
98
99```js
100import inputMethod from '@ohos.inputmethod';
101let inputMethodSetting = inputMethod.getSetting();
102inputMethodSetting.showOptionalInputMethods().then((data) => {
103    console.info('Succeeded in showing optionalInputMethods.');
104}).catch((err) => {
105    console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
106})
107```
108
109## cl.inputmethod_frameworks.2 Deprecation of Some APIs
110
111Deprecated APIs:
112  - getInputMethodSetting(): InputMethodSetting;
113  - getInputMethodController(): InputMethodController;
114  - listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void;
115  - listInputMethod(): Promise<Array<InputMethodProperty>>;
116  - displayOptionalInputMethod(callback: AsyncCallback<void>): void;
117  - displayOptionalInputMethod(): Promise<void>;
118  - stopInput(callback: AsyncCallback<boolean>): void;
119  - stopInput(): Promise<boolean>;
120    interface InputMethodProperty:
121    - readonly packageName: string;
122	- readonly methodId: string;
123  - getInputMethodEngine(): InputMethodEngine;
124  - createKeyboardDelegate(): KeyboardDelegate;
125  - hideKeyboard(callback: AsyncCallback<void>): void;
126  - hideKeyboard(): Promise<void>;
127
128Substitute APIs:
129  - getSetting(): InputMethodSetting;
130  - getController(): InputMethodController;
131  - getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
132  - getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
133  - showOptionalInputMethods(callback: AsyncCallback<boolean>): void;
134  - showOptionalInputMethods(): Promise<boolean>;
135  - stopInputSession(callback: AsyncCallback<boolean>): void;
136  - stopInputSession(): Promise<boolean>;
137    interface InputMethodProperty:
138    - readonly name: string;
139	- readonly id: string;
140  - getInputMethodAbility(): InputMethodAbility;
141  - getKeyboardDelegate(): KeyboardDelegate;
142  - hide(callback: AsyncCallback<void>): void;
143  - hide(): Promise<void>;
144
145**NOTE**
146
147-    Use the **getInputMethodAbility()** API to obtain an **InputMethodAbility** object, and do not use **getInputMethodEngine()** to obtain an **InputMethodEngine** object.
148- Use methods in **InputMethodAbility**, and do not use methods in **InputMethodEngine**.
149- Use the **on('inputStart')** method in **InputMethodAbility** to obtain a **KeyboardController** instance and an **InputClient** instance, and do not use the **on('inputStart')** method in **InputMethodEngine** to obtain a **TextInputClient** instance.
150
151Before:
152
153```js
154inputMethodEngine.getInputMethodEngine().on('inputStart', (kbController, textClient) => {
155    let keyboardController = kbController;
156    let textInputClient = textClient;  // Obtain a TextInputClient instance.
157});
158```
159
160After:
161```js
162inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, client) => {
163    let keyboardController = kbController;
164    let inputClient = client;  // // Obtain an InputClient instance.
165});
166```
167
168## cl.inputmethod_frameworks.3 Change of Some APIs
169
170Before change:
171  - listInputMethod(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
172  - listInputMethod(enable: boolean): Promise<Array<InputMethodProperty>>;
173  - terminateSelf(callback: AsyncCallback<void>): void;
174  - terminateSelf(): Promise<void>;
175
176After change:
177  - getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
178  - getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
179  - destroy(callback: AsyncCallback<void>): void;
180  - destroy(): Promise<void>;
181
182Deleted APIs in API version 9:
183  - startAbility(want: Want, callback: AsyncCallback<void>): void;
184  - startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;
185  - startAbility(want: Want, options?: StartOptions): Promise<void>;
186
187Added APIs:
188  - on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
189  - off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
190  - interface InputMethodProperty:
191    - readonly label?: string;
192	- readonly icon?: string;
193	- readonly iconId?: number;
194	- extra: object;
195
196  - interface InputMethodAbility:
197    - on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void;
198    - off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void;
199