Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members

scim_imengine.h

Go to the documentation of this file.
00001 /** 00002 * @file scim_imengine.h 00003 * @brief Defines scim::IMEngineFactoryBase and scim::IMEngineInstanceBase interfaces. 00004 * 00005 * scim::IMEngineFactoryBase and scim::IMEngineInstanceBase are the most important 00006 * part of SCIM platform. 00007 * 00008 * These interfaces are used to writing input method engine modules. 00009 */ 00010 00011 /* 00012 * Smart Common Input Method 00013 * 00014 * Copyright (c) 2004 James Su <suzhe@tsinghua.org.cn> 00015 * Copyright (c) 2004 James Su <suzhe@turbolinux.com.cn> 00016 * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn> 00017 * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn> 00018 * 00019 * 00020 * This library is free software; you can redistribute it and/or 00021 * modify it under the terms of the GNU Lesser General Public 00022 * License as published by the Free Software Foundation; either 00023 * version 2 of the License, or (at your option) any later version. 00024 * 00025 * This library is distributed in the hope that it will be useful, 00026 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00027 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00028 * GNU Lesser General Public License for more details. 00029 * 00030 * You should have received a copy of the GNU Lesser General Public 00031 * License along with this program; if not, write to the 00032 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 00033 * Boston, MA 02111-1307 USA 00034 * 00035 * $Id: scim_imengine.h,v 1.5 2004/07/20 10:33:53 suzhe Exp $ 00036 */ 00037 00038 #ifndef __SCIM_IMENGINE_H 00039 #define __SCIM_IMENGINE_H 00040 00041 namespace scim { 00042 /** 00043 * @addtogroup IMEngine 00044 * The base classes for input method engine modules. 00045 * @{ 00046 */ 00047 00048 /** 00049 * @brief An exception class to hold IMEngine related errors. 00050 * 00051 * scim::IMEngineBase and its derived classes must throw 00052 * scim::IMEngineError object when error. 00053 */ 00054 class IMEngineError: public Exception 00055 { 00056 public: 00057 IMEngineError (const String& what_arg) 00058 : Exception (String("scim::IMEngine: ") + what_arg) { } 00059 }; 00060 00061 class IMEngineFactoryBase; 00062 class IMEngineInstanceBase; 00063 00064 /** 00065 * @typedef typedef Pointer <IMEngineFactoryBase> IMEngineFactoryPointer; 00066 * 00067 * A smart pointer for scim::IMEngineFactoryBase and its derived classes. 00068 */ 00069 typedef Pointer <IMEngineFactoryBase> IMEngineFactoryPointer; 00070 00071 /** 00072 * @typedef typedef Pointer <IMEngineInstanceBase> IMEngineInstancePointer; 00073 * 00074 * A smart pointer for scim::IMEngineInstanceBase and its derived classes. 00075 */ 00076 typedef Pointer <IMEngineInstanceBase> IMEngineInstancePointer; 00077 00078 typedef Slot1<void, IMEngineInstanceBase*> 00079 IMEngineSlotVoid; 00080 00081 typedef Slot2<void, IMEngineInstanceBase*,int> 00082 IMEngineSlotInt; 00083 00084 typedef Slot2<void, IMEngineInstanceBase*,bool> 00085 IMEngineSlotBool; 00086 00087 typedef Slot2<void, IMEngineInstanceBase*,const WideString&> 00088 IMEngineSlotWideString; 00089 00090 typedef Slot2<void, IMEngineInstanceBase*,const KeyEvent&> 00091 IMEngineSlotKeyEvent; 00092 00093 typedef Slot2<void, IMEngineInstanceBase*,const LookupTable&> 00094 IMEngineSlotLookupTable; 00095 00096 typedef Slot2<void, IMEngineInstanceBase*,const Property&> 00097 IMEngineSlotProperty; 00098 00099 typedef Slot2<void, IMEngineInstanceBase*,const PropertyList&> 00100 IMEngineSlotPropertyList; 00101 00102 typedef Slot3<void, IMEngineInstanceBase*,const WideString&,const AttributeList&> 00103 IMEngineSlotWideStringAttributeList; 00104 00105 /** 00106 * @brief The base class of the real input methods' IMEngineFactory classes. 00107 * 00108 * Each input method should implement a class derived from scim::IMEngineFactoryBase, 00109 * which takes charge of holding shared data, creating IMEngineInstances etc. 00110 */ 00111 class IMEngineFactoryBase : public ReferencedObject 00112 { 00113 class IMEngineFactoryBaseImpl; 00114 00115 IMEngineFactoryBaseImpl *m_impl; 00116 00117 public: 00118 IMEngineFactoryBase (); 00119 00120 /** 00121 * @brief Virtual destructor. 00122 */ 00123 virtual ~IMEngineFactoryBase (); 00124 00125 /** 00126 * @name Pure virtual members. 00127 * 00128 * These member functions must be implemented in derived classes. 00129 * 00130 * @{ 00131 */ 00132 00133 /** 00134 * @brief Get the name of this input method engine. 00135 * 00136 * This name should be a localized string. 00137 * 00138 * @return A WideString containing the name. 00139 */ 00140 virtual WideString get_name () const = 0; 00141 00142 /** 00143 * @brief Get the UUID of this input method engine. 00144 * 00145 * Each input method engine has an unique UUID to 00146 * distinguish itself from other engines. 00147 * 00148 * You may use uuidgen command shipped with e2fsprogs package to generate this UUID. 00149 * 00150 * @return A String containing an unique UUID. 00151 */ 00152 virtual String get_uuid () const = 0; 00153 00154 /** 00155 * @brief Get the icon file path of this input method engine. 00156 * 00157 * @return A String containing the icon file path on the local filesystem. 00158 */ 00159 virtual String get_icon_file () const = 0; 00160 00161 /** 00162 * @brief Get the authors information of this input method engine. 00163 * 00164 * This string should be a localized string. 00165 * 00166 * @return A WideString containing a list of the authors' name. 00167 */ 00168 virtual WideString get_authors () const = 0; 00169 00170 /** 00171 * @brief Get the credits information of this input method engine. 00172 * 00173 * This string should be a localized string. 00174 * 00175 * @return A WideString containing the credits information. 00176 */ 00177 virtual WideString get_credits () const = 0; 00178 00179 /** 00180 * @brief Get the help information of this input method engine. 00181 * 00182 * This string should be a localized string. 00183 * 00184 * @return A WideString containing the help information. 00185 */ 00186 virtual WideString get_help () const = 0; 00187 00188 /** 00189 * @brief Create a new IMEngineInstance object. 00190 * 00191 * This method creates a new scim::IMEngineInstanceBase object with the given encoding and id. 00192 * 00193 * @param encoding - the encoding supported by the client. 00194 * @param id - the instance id, should be unique. 00195 * @return A smart pointer points to this new IMEngineInstance object. 00196 */ 00197 virtual IMEngineInstancePointer create_instance (const String& encoding, int id = -1) = 0; 00198 /** 00199 * @} 00200 */ 00201 00202 /** 00203 * @brief Check if a encoding is supported by this IMEngineFactory. 00204 * 00205 * The default implementation of this virtual function validates the 00206 * encoding against the locale list set by method set_locales. 00207 * 00208 * It should be enough in most case. 00209 * 00210 * @param encoding - the encoding name to be checked. 00211 * @return true if the encoding is supported, otherwise false. 00212 */ 00213 virtual bool validate_encoding (const String& encoding) const; 00214 00215 /** 00216 * @brief Check if a locale is supported by this IMEngineFactory. 00217 * 00218 * The default implementation of this virtual function validates the 00219 * locale against the locale list set by method set_locales. 00220 * 00221 * It should be enough in most case. 00222 * 00223 * @param locale - the locale name to be checked. 00224 * @return true if the locale is supported, otherwise false. 00225 */ 00226 virtual bool validate_locale (const String& locale) const; 00227 00228 /** 00229 * @brief Get the supported language of this input method engine. 00230 * 00231 * The language name conforms to glibc locale naming standard, like: 00232 * zh_CN Simplified Chinese 00233 * zh_TW Traditional Chinese 00234 * ja_JP Japanese 00235 * ru_RU for Russian 00236 * 00237 * The second part of the name (territory id) can be omitted. 00238 * 00239 * The default implementation of this method will get the language name 00240 * according to the return value of get_default_locale () method. 00241 * 00242 * This method maybe overwrited to return another language name, 00243 * for example returning "~other" means other uncategorized languages. 00244 */ 00245 virtual String get_language () const; 00246 00247 /** 00248 * @brief Get the original key string of a composed string. 00249 * 00250 * For example, in the pinyin input method of Simplified Chinese: 00251 * the key string of composed string "中国" can be "zhongguo". 00252 * 00253 * The default implementation just returns a empty string. 00254 * 00255 * @param str The composed string to be queried. 00256 * 00257 * @return the original key string of the given composed string. 00258 */ 00259 virtual WideString inverse_query (const WideString &str); 00260 00261 /** 00262 * @brief Get the default locale of this input method engine. 00263 * 00264 * The default locale is the first locale in the locale list, 00265 * which is set by method set_locales. 00266 * 00267 * @return The default locale name. 00268 */ 00269 String get_default_locale () const; 00270 00271 /** 00272 * @brief Get the default encoding of this input method engine. 00273 * 00274 * The default encoding is the first locale's encoding in the locale list, 00275 * which is set by method set_locales. 00276 * 00277 * @return The default encoding name. 00278 */ 00279 String get_default_encoding () const; 00280 00281 /** 00282 * @brief Get a list of all supported locales, separated by comma. 00283 * 00284 * @return A comma separated locale list. 00285 */ 00286 String get_locales () const; 00287 00288 /** 00289 * @brief Get a list of all supported encodings, separated by comma. 00290 * 00291 * @return A comma separated encoding list. 00292 */ 00293 String get_encodings () const; 00294 00295 protected: 00296 /** 00297 * @brief Set the locales supported by this input method engine. 00298 * 00299 * This method should be called within the constructors of the derived classes. 00300 * 00301 * set_locales () and set_languages () are exclusive with each other. Only one 00302 * method should be used for one Factory object. 00303 * 00304 * @param locales - a comma separated list containing all valid locales 00305 * should be supported by this input method engine. 00306 * The first locale is the default one. 00307 */ 00308 void set_locales (const String &locales); 00309 00310 /** 00311 * @brief Set the languages supported by this input method engine. 00312 * 00313 * This method should be called within the constructors of the derived classes. 00314 * 00315 * set_locales () and set_languages () are exclusive with each other. Only one 00316 * method should be used for one Factory object. 00317 * 00318 * @param languages - a comma separated list containing all valid languages 00319 * should be supported by this input method engine. 00320 * The first language is the default one. 00321 */ 00322 void set_languages (const String &languages); 00323 }; 00324 00325 /** 00326 * @brief The base class of the real input methods' IMEngineInstance classes. 00327 * 00328 * Each input method should implement a class derived from scim::IMEngineInstanceBase, 00329 * which takes charge of recording Input Context status and processing user input events. 00330 */ 00331 class IMEngineInstanceBase : public ReferencedObject 00332 { 00333 class IMEngineInstanceBaseImpl; 00334 00335 IMEngineInstanceBaseImpl *m_impl; 00336 00337 public: 00338 /** 00339 * @brief Constructor. 00340 * 00341 * @param factory - the factory which creates this instance. 00342 * @param encoding - the working encoding. 00343 * @param id - the unique id of this instance. 00344 */ 00345 IMEngineInstanceBase (IMEngineFactoryBase *factory, 00346 const String &encoding, 00347 int id = -1); 00348 00349 /** 00350 * @brief Virtual destructor. 00351 */ 00352 virtual ~IMEngineInstanceBase (); 00353 00354 /** 00355 * @brief Set the working encoding for this instance. 00356 * 00357 * One engine instance can only support one client encoding at the same time. 00358 * This encoding must be supported by the IMEngineFactory as well. 00359 * 00360 * @return true if the encoding is supported, otherwise false. 00361 */ 00362 bool set_encoding (const String &encoding); 00363 00364 /** 00365 * @brief Get the working encoding of this instance. 00366 * 00367 * @return The current working encoding. 00368 */ 00369 String get_encoding () const; 00370 00371 /** 00372 * @brief Get the unique id of this instance. 00373 * 00374 * @return The id of this instance. 00375 */ 00376 int get_id () const; 00377 00378 /** 00379 * @brief Get the UUID of the engine factory. 00380 * 00381 * @return The UUID string of the engine factory. 00382 */ 00383 String get_factory_uuid () const; 00384 00385 public: 00386 /** 00387 * @name Signal connection functions. 00388 * 00389 * These functions are used by FrontEnds to connect their corresponding slots to 00390 * this IMEngineInstance's signals. 00391 * 00392 * @{ 00393 */ 00394 Connection signal_connect_show_preedit_string (IMEngineSlotVoid *slot); 00395 Connection signal_connect_show_aux_string (IMEngineSlotVoid *slot); 00396 Connection signal_connect_show_lookup_table (IMEngineSlotVoid *slot); 00397 Connection signal_connect_hide_preedit_string (IMEngineSlotVoid *slot); 00398 Connection signal_connect_hide_aux_string (IMEngineSlotVoid *slot); 00399 Connection signal_connect_hide_lookup_table (IMEngineSlotVoid *slot); 00400 Connection signal_connect_update_preedit_caret (IMEngineSlotInt *slot); 00401 Connection signal_connect_update_preedit_string (IMEngineSlotWideStringAttributeList *slot); 00402 Connection signal_connect_update_aux_string (IMEngineSlotWideStringAttributeList *slot); 00403 Connection signal_connect_update_lookup_table (IMEngineSlotLookupTable *slot); 00404 Connection signal_connect_commit_string (IMEngineSlotWideString *slot); 00405 Connection signal_connect_forward_key_event (IMEngineSlotKeyEvent *slot); 00406 Connection signal_connect_register_properties (IMEngineSlotPropertyList *slot); 00407 Connection signal_connect_update_property (IMEngineSlotProperty *slot); 00408 /** @} */ 00409 00410 public: 00411 /** 00412 * @name Action functions. 00413 * 00414 * These functions will be called by FrontEnds to send events to 00415 * this IMEngineInstance. 00416 * 00417 * @{ 00418 */ 00419 00420 /** 00421 * @brief Process a key event. 00422 * 00423 * @param key - the key event to be processed. 00424 * @return true if the event is processed, otherwise the event 00425 * is not processed and should be forward to client application. 00426 */ 00427 virtual bool process_key_event (const KeyEvent &key) = 0; 00428 00429 /** 00430 * @brief Move the preedit caret in the preedit string. 00431 * 00432 * @param pos - the new position that user requested. 00433 */ 00434 virtual void move_preedit_caret (unsigned int pos) = 0; 00435 00436 /** 00437 * @brief Select a candidate in current lookup table. 00438 * 00439 * When user click a candidate directly, 00440 * this method will be invoked by FrontEnd. 00441 * 00442 * @param index - the index in current page of the selected candidate. 00443 */ 00444 virtual void select_candidate (unsigned int index) = 0; 00445 00446 /** 00447 * @brief Update the page size of current lookup table. 00448 * 00449 * In the next time, the lookup table should page down by 00450 * this size. 00451 * 00452 * @param page_size - the new size of current page. 00453 */ 00454 virtual void update_lookup_table_page_size (unsigned int page_size) = 0; 00455 00456 /** 00457 * @brief Flip the lookup table to the previous page. 00458 * 00459 * The method will be invoked by FrontEnd when user click 00460 * the lookup table page up button. 00461 */ 00462 virtual void lookup_table_page_up () = 0; 00463 00464 /** 00465 * @brief Flip the lookup table to the next page. 00466 * 00467 * The method will be invoked by FrontEnd when user click 00468 * the lookup table page down button. 00469 */ 00470 virtual void lookup_table_page_down () = 0; 00471 00472 /** 00473 * @brief Reset this engine instance. 00474 * 00475 * All status of this engine instance should be reset, 00476 * including the working encoding. 00477 */ 00478 virtual void reset () = 0; 00479 00480 /** 00481 * @brief Focus in this engine instance. 00482 * 00483 * This function should update/show/hide the status area, 00484 * preedit area and lookup table, and update the 00485 * full width punctuation/letter state. 00486 */ 00487 virtual void focus_in () = 0; 00488 00489 /** 00490 * @brief Focus out this engine instance. 00491 */ 00492 virtual void focus_out () = 0; 00493 00494 /** 00495 * @brief Trigger a property. 00496 * 00497 * This function should do some action according 00498 * to the triggered property. 00499 * For example toggle the input mode, etc. 00500 * 00501 * @param property the key of the triggered property. 00502 */ 00503 virtual void trigger_property (const String &property) = 0; 00504 00505 /** @} */ 00506 00507 protected: 00508 /** 00509 * @name Signal activation functions 00510 * 00511 * These functions should be called by derived classes 00512 * to fire the corresponding signals. The FrontEnd 00513 * connected to those signals will receive and process them. 00514 * 00515 * @{ 00516 */ 00517 00518 /** 00519 * @brief Show the preedit string area. 00520 * 00521 * The preedit string should be updated by calling 00522 * update_preedit_string before or right after this call. 00523 */ 00524 void show_preedit_string (); 00525 00526 /** 00527 * @brief Show the aux string area. 00528 * 00529 * The aux string should be updated by calling 00530 * update_aux_string before or right after this call. 00531 * 00532 * The aux string can contain any additional information whatever 00533 * the input method engine want. 00534 */ 00535 void show_aux_string (); 00536 00537 /** 00538 * @brief Show the lookup table area. 00539 * 00540 * The lookup table should be updated by calling 00541 * update_lookup_table before or right after this call. 00542 */ 00543 void show_lookup_table (); 00544 00545 /** 00546 * @brief Hide the preedit string area. 00547 */ 00548 void hide_preedit_string (); 00549 00550 /** 00551 * @brief Hide the aux string area. 00552 */ 00553 void hide_aux_string (); 00554 00555 /** 00556 * @brief Hide the lookup table area. 00557 */ 00558 void hide_lookup_table (); 00559 00560 /** 00561 * @brief Update the preedit caret position in the preedit string. 00562 * 00563 * @param caret - the new position of the preedit caret. 00564 */ 00565 void update_preedit_caret (int caret); 00566 00567 /** 00568 * @brief Update the content of the preedit string, 00569 * 00570 * @param str - the string content 00571 * @param attrs - the string attributes 00572 */ 00573 void update_preedit_string (const WideString &str, 00574 const AttributeList &attrs = AttributeList ()); 00575 00576 /** 00577 * @brief Update the content of the aux string, 00578 * 00579 * @param str - the string content 00580 * @param attrs - the string attribute 00581 */ 00582 void update_aux_string (const WideString &str, 00583 const AttributeList &attrs = AttributeList ()); 00584 00585 /** 00586 * @brief Update the content of the lookup table, 00587 * 00588 * FrontEnd may reduce the page size of the table 00589 * according to screen resolution. If the page size 00590 * is changed, FrontEnd will inform this engine instance 00591 * by calling update_lookup_table_page_size method. 00592 * 00593 * @param table - the new LookupTable 00594 */ 00595 void update_lookup_table (const LookupTable &table); 00596 00597 /** 00598 * @brief Commit a string to the client application. 00599 * 00600 * The preedit string should be hid before calling 00601 * this method. Otherwise the clients which use 00602 * OnTheSpot input mode will flicker annoyingly. 00603 * 00604 * @param str - the string to be committed. 00605 */ 00606 void commit_string (const WideString &str); 00607 00608 /** 00609 * @brief Forward a key event to the client application. 00610 * 00611 * @param key - the key event to be forwarded. 00612 */ 00613 void forward_key_event (const KeyEvent &key); 00614 00615 /** 00616 * @brief Register all properties of this IMEngineInstance into the FrontEnd. 00617 * 00618 * The old properties previously registered by other IMEngineInstance will be discarded. 00619 * 00620 * @param properties the PropertyList contains all of the properties. 00621 */ 00622 void register_properties (const PropertyList &properties); 00623 00624 /** 00625 * @brief Update a registered property. 00626 * 00627 * Update a property which already registered by register_properties () method. 00628 * 00629 * @param property the property to be updated. 00630 */ 00631 void update_property (const Property &property); 00632 /** @} */ 00633 }; 00634 00635 /** 00636 * @brief A trivial IMEngine that do nothing. 00637 */ 00638 class DummyIMEngineFactory : public IMEngineFactoryBase 00639 { 00640 public: 00641 DummyIMEngineFactory (); 00642 virtual ~DummyIMEngineFactory (); 00643 00644 virtual WideString get_name () const; 00645 virtual String get_uuid () const; 00646 virtual String get_icon_file () const; 00647 virtual WideString get_authors () const; 00648 virtual WideString get_credits () const; 00649 virtual WideString get_help () const; 00650 00651 virtual bool validate_encoding (const String& encoding) const; 00652 virtual bool validate_locale (const String& locale) const; 00653 00654 virtual IMEngineInstancePointer create_instance (const String& encoding, int id = -1); 00655 }; 00656 00657 class DummyIMEngineInstance : public IMEngineInstanceBase 00658 { 00659 public: 00660 DummyIMEngineInstance (DummyIMEngineFactory *factory, 00661 const String &encoding, 00662 int id = -1); 00663 00664 virtual ~DummyIMEngineInstance (); 00665 00666 virtual bool process_key_event (const KeyEvent& key); 00667 virtual void move_preedit_caret (unsigned int pos); 00668 virtual void select_candidate (unsigned int index); 00669 virtual void update_lookup_table_page_size (unsigned int page_size); 00670 virtual void lookup_table_page_up (); 00671 virtual void lookup_table_page_down (); 00672 virtual void reset (); 00673 virtual void focus_in (); 00674 virtual void focus_out (); 00675 virtual void trigger_property (const String& property); 00676 }; 00677 00678 /** @} */ 00679 00680 } // namespace scim 00681 00682 #endif //__SCIM_IMENGINE_H 00683 00684 /* 00685 vi:ts=4:nowrap:ai:expandtab 00686 */ 00687

Generated on Thu Dec 30 21:03:19 2004 for scim by doxygen 1.3.8