|
1 /* |
|
2 * Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Predective text input engine core interface. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
24 |
|
25 |
|
26 |
|
27 |
|
28 |
|
29 |
|
30 |
|
31 #ifndef _PTI_CORE_H |
|
32 #define _PTI_CORE_H |
|
33 |
|
34 // INCLUDES |
|
35 #include <badesca.h> |
|
36 #include "PtiDefs.h" |
|
37 #include "PtiLanguage.h" |
|
38 #include "PtiUserDictionary.h" |
|
39 |
|
40 // FORWARD DECLARATIONS |
|
41 class CPtiEngine; |
|
42 class MPtiEngineCompositionDataInterface; |
|
43 class MPtiUserDictionaryEntry; |
|
44 |
|
45 // CONSTANTS |
|
46 const TInt KDefaultCoresGran = 3; |
|
47 |
|
48 /** |
|
49 * This is abstract base class of all PtiEngine core objects. A PtiEngine core object implements set of |
|
50 * input modes and input related services for a set of languages. This class defines core side |
|
51 * PtiEngine API. |
|
52 */ |
|
53 class MPtiCore |
|
54 { |
|
55 // |
|
56 // General API |
|
57 // |
|
58 public: |
|
59 /** |
|
60 * Initialized core object. This method is called by PtiEngine framework when core object |
|
61 * is loaded. |
|
62 * |
|
63 * @since 2.6 |
|
64 * @param aOwner Pointer to onwing PtiEngine framework instance. |
|
65 * @param aTextBuffer A pointer to PtiEngine main text buffer. |
|
66 * @param aLanguageList A language list to be filled with language bindings to this core |
|
67 * onbject |
|
68 * @param aUseDefautUserDictionary A boolean value indicating whether default user dictionary shoulkd be used |
|
69 * (in case this core object supports user dictionaries). |
|
70 */ |
|
71 virtual void InitializeL(CPtiEngine* aOwner, TDes* aTextBuffer, CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList, TBool aUseDefautUserDictionary) = 0; |
|
72 |
|
73 /** |
|
74 * Removes languages associated to this core object from given language list. Languages |
|
75 * not associated to this core abject are not touched. |
|
76 * |
|
77 * @since 2.6 |
|
78 * @param aLanguageList A language list to be cleaned. |
|
79 */ |
|
80 virtual void DropLanguages(CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList) = 0; |
|
81 |
|
82 /** |
|
83 * Opens resources for given language and itinialized them. |
|
84 * |
|
85 * @since 2.6 |
|
86 * @param aLanguage Symbian OS language code a language to be initialized. |
|
87 * @return KErrNone or a system wide error code. |
|
88 */ |
|
89 virtual TInt OpenLanguageL(CPtiCoreLanguage *aLanguage) = 0; |
|
90 |
|
91 /** |
|
92 * Closes currently activate language and frees resources associated to it. |
|
93 * |
|
94 * @since 2.6 |
|
95 * @return KErrNone of system wide error ocde. |
|
96 */ |
|
97 virtual TInt CloseLanguageL() = 0; |
|
98 |
|
99 /** |
|
100 * Returns the contents of text buffer. |
|
101 * |
|
102 * @since 2.6 |
|
103 * @return A constant pointer to text buffer. |
|
104 */ |
|
105 virtual TPtrC GetCurrentWord() const = 0; |
|
106 |
|
107 /** |
|
108 * Commits current word. Commiting means that user has added current |
|
109 * word as part of text. Frequency information and other related attributes |
|
110 * can then be updated. |
|
111 * |
|
112 * @since 2.6 |
|
113 * @return KErrNone or a system wide error code. |
|
114 */ |
|
115 virtual TInt CommitCurrentWord() = 0; |
|
116 |
|
117 /** |
|
118 * Returns a pointer core info structure. Core info struct contains useful |
|
119 * information about core object and its features. |
|
120 * |
|
121 */ |
|
122 virtual MPtiCoreInfo* GetCoreInfo() = 0; |
|
123 |
|
124 /** |
|
125 * Turns reoreding feature on or off. Reordering means that prediction engine |
|
126 * maintains frequency information for used words and modifys the order of candidate list |
|
127 * based on that information. This feature may not be supported by all prediction engines. |
|
128 * |
|
129 * @since 2.6 |
|
130 * @param aStatus New status for reorderinf feature. |
|
131 * @return KErrNone or a system wide error code. |
|
132 */ |
|
133 virtual TInt SetReordering(TBool aStatus) = 0; |
|
134 |
|
135 /** |
|
136 * This is the single most important core API method, most of the text input functionality |
|
137 * will be utilize this method. Call to this method indicates core object that a key was |
|
138 * pressed and it should act accordingly and fill the output buffer. |
|
139 * |
|
140 * @since 2.6 |
|
141 * @param aKey Enum value for pressed key. |
|
142 */ |
|
143 virtual void AppendKeyPress(TPtiKey aKey) = 0; |
|
144 |
|
145 /** |
|
146 * Indicates core object that it should perform 'delete key press'-operation. |
|
147 * |
|
148 * @since 2.6 |
|
149 */ |
|
150 virtual void DeleteKeyPress() = 0; |
|
151 |
|
152 /** |
|
153 * Call to this method notifys core object that input buffer was cleared. |
|
154 * |
|
155 * @since 2.6 |
|
156 */ |
|
157 virtual void ClearBuffer() = 0; |
|
158 |
|
159 /** |
|
160 * Sets current input sequence. The end result of this operation must be same as |
|
161 * if user had entered keys in input array as individual key presses. |
|
162 * |
|
163 * @since 2.6 |
|
164 * @param aInput An array containing sequence of key presses (type TPtiKey). |
|
165 * @return KErrNone or a system wide error code. |
|
166 */ |
|
167 virtual TInt SetCurrentInputSequence(TPtrC8 aInput) = 0; |
|
168 |
|
169 /** |
|
170 * Converts given string from one character set to another. Possible conversion types |
|
171 * are defined in PtiDefs.h |
|
172 * |
|
173 * @since 2.6 |
|
174 * @param aType Conversion type. |
|
175 * @param aInput Pointer to input string to be converted. |
|
176 * @param aInputLength Length of input buffer. |
|
177 * @param aOutput pointer to output buffer. |
|
178 * @return KErrNone or a system wide error code. |
|
179 */ |
|
180 virtual TInt Convert(TPtiCharConversion aType, |
|
181 TAny* aInput, |
|
182 TInt aInputLength, |
|
183 TAny* aOutput) = 0; |
|
184 |
|
185 /** |
|
186 * Re-defines keymappings for given key / input mode / case combination. Previous |
|
187 * keymapping will be deleted and new mappings will be used instead. |
|
188 * |
|
189 * @since 2.6 |
|
190 * @param aMode Input mode for new key mapping. |
|
191 * @param aKey A key to be replaced. |
|
192 * @param aKeyMap New keymapping data for aKey. |
|
193 * @param aCase Text case to be replaced. |
|
194 * @return KErrNone or system wide error code. |
|
195 */ |
|
196 virtual TInt SetExternalKeyMapL(TPtiEngineInputMode aMode, |
|
197 TPtiKey aKey, |
|
198 TDesC& aKeyMap, |
|
199 TPtiTextCase aCase) = 0; |
|
200 /** |
|
201 * Returns alternate spelling for given unicode characters. Possible conversion |
|
202 * types are defined in header PtiDefs.h. |
|
203 * |
|
204 * @sinec 2.6 |
|
205 * @aInput A character to be converted. |
|
206 * @aOutput Resulting alternate spelling will be stored here. |
|
207 * @aType Spelling conversion type. |
|
208 * @return KErrNone or system wide error code. |
|
209 */ |
|
210 virtual TInt GetSpelling(TUint16 aInput, TDes& aOutput, TPtiSpelling aType) = 0; |
|
211 |
|
212 /** |
|
213 * Cancels all on-going core obejct timner activity. |
|
214 * |
|
215 * @since 2.6 |
|
216 * @return KErrNone or system wide error code. |
|
217 */ |
|
218 virtual TInt CancelTimerActivity() = 0; |
|
219 |
|
220 /** |
|
221 * A generic command handling method for extending PtiEngine API without adding |
|
222 * new base class methods. It is recommended to use this only in force major |
|
223 * situations, where there is no other way. |
|
224 * |
|
225 * @since 2.6 |
|
226 * @param aCommand A Command id value. Platform wide command ids are defined in PtiDefs.h. |
|
227 * @param aParams TAny pointer for passing any required parameters. |
|
228 * @return An integer containing possible return value related to command. |
|
229 */ |
|
230 virtual TInt HandleCommandL(TPtiEngineCommand aCommand, TAny* aParams) = 0; |
|
231 |
|
232 // |
|
233 // Predictive latin API |
|
234 // |
|
235 public: |
|
236 /** |
|
237 * Returns number of candidates for currently entered key sequence. |
|
238 * |
|
239 * @since 2.6 |
|
240 * @return Number of prediction candidates for currently entered key sequence. |
|
241 */ |
|
242 virtual TInt NumberOfCandidates() = 0; |
|
243 |
|
244 /** |
|
245 * Returns a list of candidate words for currently entered key sequence. |
|
246 * |
|
247 * @since 2.6 |
|
248 * @param aList A list to be filled with candidate words. |
|
249 * @return Number of candidate works in aList. |
|
250 */ |
|
251 virtual TInt GetCandidateListL(CDesCArray& aList) = 0; |
|
252 |
|
253 /** |
|
254 * Returns next word candidate list. Next word candidates are words |
|
255 * potentially related to currently selected candidate. Next word prediction |
|
256 * feature must supported by the engine and turned on. |
|
257 * |
|
258 * @since 2.6 |
|
259 */ |
|
260 virtual TInt GetNextWordCandidateListL(CDesCArray& aList) = 0; |
|
261 |
|
262 /** |
|
263 * Returns first word in list of candidate words for current input sequence. |
|
264 * |
|
265 * @since 2.6 |
|
266 * @param aResult A descriptor where resulting word will be stored. |
|
267 * @return KErrnNone or system wide error code. |
|
268 */ |
|
269 virtual TInt GetFirstCandidate(TDes& aResult) = 0; |
|
270 |
|
271 /** |
|
272 * Returns next word in list of candidate words for current input sequence. |
|
273 * |
|
274 * @since 2.6 |
|
275 * @param aResult A descriptor where resulting word will be stored. |
|
276 * @return KErrnNone or system wide error code. |
|
277 */ |
|
278 virtual TInt GetNextCandidate(TDes& aResult) = 0; |
|
279 |
|
280 /** |
|
281 * Returns previous word in list of candidate words for current input sequence. |
|
282 * |
|
283 * @since 2.6 |
|
284 * @param aResult A descriptor where resulting word will be stored. |
|
285 * @return KErrnNone or system wide error code. |
|
286 */ |
|
287 virtual TInt GetPreviousCandidate(TDes& aResult) = 0; |
|
288 |
|
289 // |
|
290 // User dictionary API |
|
291 // |
|
292 public: |
|
293 virtual TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0; |
|
294 virtual TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0; |
|
295 virtual TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict) = 0; |
|
296 virtual TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict) = 0; |
|
297 virtual CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize) = 0; |
|
298 virtual TInt AttachUserDictionary(CPtiUserDictionary* aDict) = 0; |
|
299 virtual TBool DetachUserDictionary(CPtiUserDictionary* aDict) = 0; |
|
300 |
|
301 // |
|
302 // Chinese API |
|
303 // |
|
304 public: |
|
305 virtual TPtrC GetCandidatePage() = 0; |
|
306 virtual TBool NextCandidatePage() = 0; |
|
307 virtual TBool PreviousCandidatePage() = 0; |
|
308 virtual TBool MoreCandidatePages() = 0; |
|
309 virtual void SetCandidatePageLength(TInt aLength) = 0; |
|
310 virtual TPtrC GetPhoneticSpelling(TInt aIndex) const = 0; |
|
311 virtual TInt PhoneticSpellingCount() const = 0; |
|
312 virtual TBool SelectPhoneticSpelling(TInt aIndex) = 0; |
|
313 virtual TInt SelectedPhoneticSpelling() const = 0; |
|
314 virtual TBool ToneMark(TText& aToneMark) const = 0; |
|
315 virtual TBool IsToneMarkValidForSpelling() = 0; |
|
316 virtual TBool SetPredictiveChineseChar(const TDesC& aChar) = 0; |
|
317 virtual TBool SetToneMark(TInt aToneMark) = 0; |
|
318 |
|
319 |
|
320 // |
|
321 // Japanese API |
|
322 // |
|
323 public: |
|
324 virtual TPtrC ReadingTextL() = 0; |
|
325 virtual MPtiEngineCompositionDataInterface* CompositionData() = 0; |
|
326 |
|
327 // |
|
328 // Chinese API |
|
329 // |
|
330 public: |
|
331 virtual HBufC* GetCandidatesByInputString(const TDesC& aInputString, |
|
332 RPointerArray<HBufC>& aList, |
|
333 const TBool aIsPredictive) = 0; |
|
334 }; |
|
335 |
|
336 |
|
337 /** |
|
338 * This class is a base class implementation for MPtiCore. It contains empty base implemenations |
|
339 * for core API methods and static methods for creating and listing PtiEngine core objects. |
|
340 */ |
|
341 class CPtiCore : public CBase, public MPtiCore |
|
342 { |
|
343 // |
|
344 // Plugin household methods |
|
345 // |
|
346 public: |
|
347 /** |
|
348 * Creates in instance of core object for given implemenation uid. |
|
349 * |
|
350 * @param aCoreUid An ecom implementation uid for core object to be created. |
|
351 * @return Pointer to new core object instance. |
|
352 */ |
|
353 IMPORT_C static CPtiCore* CreateCoreL(TUid aCoreUid); |
|
354 |
|
355 /** |
|
356 * Lists all the available PtiEngine core onject implemenatations. |
|
357 * |
|
358 * @return Pointer to a list cantaining implementation uids for available core plugins. |
|
359 */ |
|
360 IMPORT_C static CArrayFix<TInt>* ListCoresLC(); |
|
361 |
|
362 public: |
|
363 IMPORT_C ~CPtiCore(); |
|
364 |
|
365 // |
|
366 // General methods. |
|
367 // |
|
368 public: |
|
369 IMPORT_C TInt SetCurrentInputSequence(TPtrC8 aInput); |
|
370 IMPORT_C TInt Convert(TPtiCharConversion aType, |
|
371 TAny* aInput, |
|
372 TInt aInputLength, |
|
373 TAny* aOutput); |
|
374 IMPORT_C TInt GetSpelling(TUint16 aInput, |
|
375 TDes& aOutput, |
|
376 TPtiSpelling aType); |
|
377 IMPORT_C TInt SetExternalKeyMapL(TPtiEngineInputMode aMode, |
|
378 TPtiKey aKey, |
|
379 TDesC& aKeyMap, |
|
380 TPtiTextCase aCase); |
|
381 IMPORT_C TInt CommitCurrentWord(); |
|
382 IMPORT_C TPtrC GetCurrentWord() const; |
|
383 |
|
384 // |
|
385 // Predictive latin API |
|
386 // |
|
387 public: |
|
388 IMPORT_C TInt NumberOfCandidates(); |
|
389 IMPORT_C TInt GetCandidateListL(CDesCArray& aList); |
|
390 IMPORT_C TInt GetNextWordCandidateListL(CDesCArray& aList); |
|
391 IMPORT_C TInt GetFirstCandidate(TDes& aResult); |
|
392 IMPORT_C TInt GetNextCandidate(TDes& aResult); |
|
393 IMPORT_C TInt GetPreviousCandidate(TDes& aResult); |
|
394 |
|
395 // |
|
396 // User dictionary API |
|
397 // |
|
398 public: |
|
399 IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict); |
|
400 IMPORT_C TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict); |
|
401 IMPORT_C TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict); |
|
402 IMPORT_C TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict); |
|
403 IMPORT_C CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize); |
|
404 IMPORT_C TInt AttachUserDictionary(CPtiUserDictionary* aDict); |
|
405 IMPORT_C TBool DetachUserDictionary(CPtiUserDictionary* aDict); |
|
406 |
|
407 // |
|
408 // Chinese API |
|
409 // |
|
410 public: |
|
411 IMPORT_C TPtrC GetCandidatePage(); |
|
412 IMPORT_C TBool NextCandidatePage(); |
|
413 IMPORT_C TBool PreviousCandidatePage(); |
|
414 IMPORT_C TBool MoreCandidatePages(); |
|
415 IMPORT_C void SetCandidatePageLength(TInt aLength); |
|
416 IMPORT_C TPtrC GetPhoneticSpelling(TInt aIndex) const; |
|
417 IMPORT_C TInt PhoneticSpellingCount() const; |
|
418 IMPORT_C TBool SelectPhoneticSpelling(TInt aIndex); |
|
419 IMPORT_C TInt SelectedPhoneticSpelling() const; |
|
420 IMPORT_C TBool ToneMark(TText& aToneMark) const; |
|
421 IMPORT_C TBool IsToneMarkValidForSpelling(); |
|
422 IMPORT_C TBool SetPredictiveChineseChar(const TDesC& aChar); |
|
423 IMPORT_C TBool SetToneMark(TInt aToneMark); |
|
424 |
|
425 // |
|
426 // Japanese API |
|
427 // |
|
428 public: |
|
429 IMPORT_C TPtrC ReadingTextL(); |
|
430 IMPORT_C MPtiEngineCompositionDataInterface* CompositionData(); |
|
431 |
|
432 // |
|
433 // Chinese API |
|
434 // |
|
435 public: |
|
436 IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString, |
|
437 RPointerArray<HBufC>& aList, |
|
438 const TBool aIsPredictive); |
|
439 |
|
440 private: |
|
441 inline void SetDestructorKeyId(TInt aDtorKeyId); |
|
442 |
|
443 private: |
|
444 TInt iDtorKeyId; |
|
445 TInt Reserved_1; |
|
446 }; |
|
447 |
|
448 |
|
449 inline void CPtiCore::SetDestructorKeyId(TInt aDtorKeyId) |
|
450 { |
|
451 iDtorKeyId = aDtorKeyId; |
|
452 } |
|
453 |
|
454 #endif _PTI_CORE_H |
|
455 |
|
456 // End of file |
|
457 |
|
458 |