00001 /** @file scim_backend.h 00002 * @brief scim::BackEndBase Interface. 00003 * 00004 * Provide an abstract interface class to 00005 * manage a set of IMEngineFactory instances. 00006 */ 00007 00008 /* 00009 * Smart Common Input Method 00010 * 00011 * Copyright (c) 2004 James Su <suzhe@turbolinux.com.cn> 00012 * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn> 00013 * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn> 00014 * 00015 * 00016 * This library is free software; you can redistribute it and/or 00017 * modify it under the terms of the GNU Lesser General Public 00018 * License as published by the Free Software Foundation; either 00019 * version 2 of the License, or (at your option) any later version. 00020 * 00021 * This library is distributed in the hope that it will be useful, 00022 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00024 * GNU Lesser General Public License for more details. 00025 * 00026 * You should have received a copy of the GNU Lesser General Public 00027 * License along with this program; if not, write to the 00028 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 00029 * Boston, MA 02111-1307 USA 00030 * 00031 * $Id: scim_backend.h,v 1.16 2004/07/24 02:14:28 suzhe Exp $ 00032 */ 00033 00034 #ifndef __SCIM_BACKEND_H 00035 #define __SCIM_BACKEND_H 00036 00037 namespace scim { 00038 00039 typedef Slot1<void, int> 00040 BackEndSlotVoid; 00041 00042 typedef Slot2<void, int, int> 00043 BackEndSlotInt; 00044 00045 typedef Slot2<void, int, bool> 00046 BackEndSlotBool; 00047 00048 typedef Slot2<void, int, const WideString&> 00049 BackEndSlotWideString; 00050 00051 typedef Slot2<void, int, const KeyEvent&> 00052 BackEndSlotKeyEvent; 00053 00054 typedef Slot2<void, int, const LookupTable&> 00055 BackEndSlotLookupTable; 00056 00057 typedef Slot2<void, int, const Property&> 00058 BackEndSlotProperty; 00059 00060 typedef Slot2<void, int, const PropertyList&> 00061 BackEndSlotPropertyList; 00062 00063 typedef Slot3<void, int, const WideString&,const AttributeList&> 00064 BackEndSlotWideStringAttributeList; 00065 00066 /** 00067 * @brief An exception class to hold BackEnd related errors. 00068 * 00069 * scim::BackEndBase and its derived classes must throw 00070 * scim::BackEndError object when error. 00071 */ 00072 class BackEndError: public Exception 00073 { 00074 public: 00075 BackEndError (const String& what_arg) 00076 : Exception (String("scim::BackEnd: ") + what_arg) { } 00077 }; 00078 00079 /** 00080 * @brief The interface class to manage a set of IMEngineFactory 00081 * and IMEngineInstance objects. 00082 * 00083 * This is mainly a helper interface class used by scim::FrontEndBase. 00084 * Its responsibility is to hold a set of IMEngineFactory instances 00085 * and manage the locales list supported by them. 00086 * 00087 * Most developer should just use the default implementation 00088 * scim::CommonBackEnd. 00089 */ 00090 class BackEndBase : public ReferencedObject 00091 { 00092 class BackEndBaseImpl; 00093 00094 BackEndBaseImpl *m_impl; 00095 00096 public: 00097 /** 00098 * @brief Default constructor. 00099 */ 00100 BackEndBase (); 00101 00102 /** 00103 * @brief Virtual destructor. 00104 */ 00105 virtual ~BackEndBase (); 00106 00107 /** 00108 * @brief Get a list of all locales supported by all FrontEnds. 00109 * @return A comma separated locales list. 00110 */ 00111 String get_all_locales () const; 00112 00113 /** 00114 * @brief Return the number of factories held by this BackEnd. 00115 */ 00116 uint32 number_of_factories () const; 00117 00118 /** 00119 * @return Return the pointer of a Factory. 00120 */ 00121 IMEngineFactoryPointer get_factory_pointer (uint32 idx) const; 00122 00123 public: 00124 /** 00125 * @name Methods to manipulate IMEngine Factories. 00126 * 00127 * @{ 00128 */ 00129 00130 /** 00131 * @brief Get the IMEngine factories list for specific encoding 00132 * 00133 * @param uuids the vector to store the factories' uuids which 00134 * support the encoding. 00135 * @param encoding the encoding to be queried. If empty, 00136 * all IMEngine factories will be returned. 00137 * 00138 * @return the number of IMEngine factories found. 00139 */ 00140 uint32 get_factory_list (std::vector<String> &uuids, const String &encoding = String ("")) const; 00141 00142 /** 00143 * @brief get the name of an IMEngine factory. 00144 * 00145 * @param uuid the uuid of the IMEngine factory 00146 * @return the name of the IMEngine factory. 00147 */ 00148 WideString get_factory_name (const String &uuid) const; 00149 00150 /** 00151 * @brief get the authors info of an IMEngine factory. 00152 * @param uuid the uuid of the IMEngine factory 00153 * @return the authors info of the IMEngine factory. 00154 */ 00155 WideString get_factory_authors (const String &uuid) const; 00156 00157 /** 00158 * @brief get the credits info of an IMEngine factory. 00159 * @param uuid the uuid of the IMEngine factory 00160 * @return the credits info of the IMEngine factory. 00161 */ 00162 WideString get_factory_credits (const String &uuid) const; 00163 00164 /** 00165 * @brief get the help info of an IMEngine factory. 00166 * @param uuid the uuid of the IMEngine factory 00167 * @return the help info of the IMEngine factory. 00168 */ 00169 WideString get_factory_help (const String &uuid) const; 00170 00171 /** 00172 * @brief get the icon file of an IMEngine factory. 00173 * @param uuid the uuid of the IMEngine factory 00174 * @return the icon file name of the IMEngine factory. 00175 */ 00176 String get_factory_icon_file (const String &uuid) const; 00177 00178 /** 00179 * @brief get the supported locales of an IMEngine factory. 00180 * @param uuid the uuid of the IMEngine factory 00181 * @return a comma separated list of the supported locales. 00182 */ 00183 String get_factory_locales (const String &uuid) const; 00184 00185 /** 00186 * @brief get the language of an IMEngine factory. 00187 * @param uuid the uuid of the IMEngine factory 00188 * @return the language of this IMEngine factory. 00189 */ 00190 String get_factory_language (const String &uuid) const; 00191 00192 /** 00193 * @} 00194 */ 00195 00196 public: 00197 /** 00198 * @name Methods to manipulate IMEngine Instances. 00199 * 00200 * @{ 00201 */ 00202 00203 /** 00204 * @brief create a new IMEngine instance for specific encoding. 00205 * 00206 * @param sf_uuid the IMEngineFactory UUID. 00207 * @param encoding the encoding to be used. 00208 * 00209 * @return the newly created IMEngine instance id, -1 means error occurred. 00210 */ 00211 int new_instance (const String &sf_uuid, const String &encoding); 00212 00213 /** 00214 * @brief replace an IMEngine instance by a new instance created by another factory. 00215 * 00216 * This function is used to change the input method for an input context on the fly. 00217 * 00218 * @param si_id the IMEngine instance to be replaced. 00219 * @param sf_uuid the new IMEngine factory to be used. 00220 */ 00221 bool replace_instance (int si_id, const String &sf_uuid); 00222 00223 /** 00224 * @brief delete an IMEngine instance according to its id. 00225 * @param id the id of the IMEngine instance to be deleted. 00226 * @return true if success, false if there is no such instance. 00227 */ 00228 bool delete_instance (int id); 00229 00230 /** 00231 * @brief delete all IMEngine instances. 00232 * 00233 * This function should be called just before quitting the FrontEnd. 00234 */ 00235 void delete_all_instances (); 00236 00237 /** 00238 * @brief get the factory uuid of this instance. 00239 * @param id the IMEngine instance id. 00240 * @return the factory uuid of this instance. 00241 */ 00242 String get_instance_uuid (int id) const; 00243 00244 /** 00245 * @brief get the working encoding of an IMEngine instance. 00246 * @param id the IMEngine instance id. 00247 * @return the working encoding of this IMEngine instance. 00248 */ 00249 String get_instance_encoding (int id) const; 00250 00251 /** 00252 * @brief get the name of an IMEngine instance. 00253 * @param id the IMEngine instance id. 00254 * @return the name of this IMEngine instance, 00255 * aka. the name of its factory. 00256 */ 00257 WideString get_instance_name (int id) const; 00258 00259 /** 00260 * @brief get the authors info of an IMEngine instance. 00261 * @param id the IMEngine instance id. 00262 * @return the authors info of this IMEngine instance, 00263 * aka. the authors of its factory. 00264 */ 00265 WideString get_instance_authors (int id) const; 00266 00267 /** 00268 * @brief get the credits info of an IMEngine instance. 00269 * @param id the IMEngine instance id. 00270 * @return the credits info of this IMEngine instance, 00271 * aka. the credits of its factory. 00272 */ 00273 WideString get_instance_credits (int id) const; 00274 00275 /** 00276 * @brief get the help of an IMEngine instance. 00277 * @param id the IMEngine instance id. 00278 * @return the help of this IMEngine instance, 00279 * aka. the help of its factory. 00280 */ 00281 WideString get_instance_help (int id) const; 00282 00283 /** 00284 * @brief get the icon file of an IMEngine instance. 00285 * @param id the IMEngine instance id. 00286 * @return the icon file name of this IMEngine instance. 00287 */ 00288 String get_instance_icon_file (int id) const; 00289 00290 /** 00291 * @brief process a key event using specific IMEngine instance. 00292 * @param id the IMEngine instance id. 00293 * @param key the key event to be processed. 00294 * @return true if the event was processed successfully, 00295 * false if the event was not processed and should 00296 * be forward to the client application. 00297 */ 00298 bool process_key_event (int id, const KeyEvent& key) const; 00299 00300 /** 00301 * @brief let a specific IMEngine instance move its preedit caret. 00302 * @param id the IMEngine instance id. 00303 * @param pos the new preedit caret position. 00304 */ 00305 void move_preedit_caret (int id, unsigned int pos) const; 00306 00307 /** 00308 * @brief let a specific IMEngine instance select a candidate in its current lookup table. 00309 * @param id the IMEngine instance id. 00310 * @param index the candidate index in current lookup table page to be selected. 00311 */ 00312 void select_candidate (int id, unsigned int index) const; 00313 00314 /** 00315 * @brief update the page size of a specific IMEngine instance's lookup table. 00316 * @param id the IMEngine instance id. 00317 * @param page_size the new page size to be used. 00318 */ 00319 void update_lookup_table_page_size (int id, unsigned int page_size) const; 00320 00321 /** 00322 * @brief Let a specific IMEngine instance flip its lookup table to the previous page. 00323 */ 00324 void lookup_table_page_up (int id) const; 00325 00326 /** 00327 * @brief Let a specific IMEngine instance flip its lookup table to the previous page. 00328 */ 00329 void lookup_table_page_down (int id) const; 00330 00331 /** 00332 * @brief reset a specific IMEngine instance. 00333 * @param id the id of the IMEngine instance to be reset. 00334 */ 00335 void reset (int id) const; 00336 00337 /** 00338 * @brief focus in a specific IMEngine instance. 00339 * @param id the id of the IMEngine instance to be focused in. 00340 */ 00341 void focus_in (int id) const; 00342 00343 /** 00344 * @brief focus out a specific IMEngine instance. 00345 * @param id the id of the IMEngine instance to be focused out. 00346 */ 00347 void focus_out (int id) const; 00348 00349 /** 00350 * @brief trigger a property of a specific IMEngine instance. 00351 * @param id the id of the IMEngine instance. 00352 * @param property the key of the property to be triggered. 00353 */ 00354 void trigger_property (int id, const String &property) const; 00355 00356 /** 00357 * @} 00358 */ 00359 public: 00360 /** 00361 * @name Signal connection methods. 00362 * 00363 * These functions are used by FrontEnds to connect their corresponding slots to 00364 * this BackEnd's signals. 00365 * 00366 * The first parameter of these methods are the id of corresponding instance. 00367 * 00368 * @{ 00369 */ 00370 Connection signal_connect_show_preedit_string (BackEndSlotVoid *slot); 00371 Connection signal_connect_show_aux_string (BackEndSlotVoid *slot); 00372 Connection signal_connect_show_lookup_table (BackEndSlotVoid *slot); 00373 Connection signal_connect_hide_preedit_string (BackEndSlotVoid *slot); 00374 Connection signal_connect_hide_aux_string (BackEndSlotVoid *slot); 00375 Connection signal_connect_hide_lookup_table (BackEndSlotVoid *slot); 00376 Connection signal_connect_update_preedit_caret (BackEndSlotInt *slot); 00377 Connection signal_connect_update_preedit_string (BackEndSlotWideStringAttributeList *slot); 00378 Connection signal_connect_update_aux_string (BackEndSlotWideStringAttributeList *slot); 00379 Connection signal_connect_update_lookup_table (BackEndSlotLookupTable *slot); 00380 Connection signal_connect_commit_string (BackEndSlotWideString *slot); 00381 Connection signal_connect_forward_key_event (BackEndSlotKeyEvent *slot); 00382 Connection signal_connect_register_properties (BackEndSlotPropertyList *slot); 00383 Connection signal_connect_update_property (BackEndSlotProperty *slot); 00384 /** @} */ 00385 00386 protected: 00387 /** 00388 * @name Methods used by derived classes. 00389 * 00390 * @{ 00391 */ 00392 00393 /** 00394 * @brief Add an IMEngineFactory object into BackEnd. 00395 */ 00396 bool add_factory (const IMEngineFactoryPointer &factory); 00397 00398 /** 00399 * @brief Set the list of unicode locales to be supported. 00400 */ 00401 void set_supported_unicode_locales (const String &locales); 00402 00403 /** 00404 * @brief Destroy all factory instances. 00405 */ 00406 void destroy_all_factories (); 00407 00408 /** 00409 * @} 00410 */ 00411 }; 00412 00413 /** 00414 * @typedef typedef Pointer <BackEndBase> BackEndPointer; 00415 * 00416 * A smart pointer for scim::BackEndBase and its derived classes. 00417 */ 00418 typedef Pointer <BackEndBase> BackEndPointer; 00419 00420 /** 00421 * @brief The default implementation of scim::BackEndBase interface. 00422 */ 00423 class CommonBackEnd : public BackEndBase 00424 { 00425 class CommonBackEndImpl; 00426 CommonBackEndImpl *m_impl; 00427 00428 public: 00429 /** 00430 * @brief Constructor 00431 * 00432 * @param config The pointer to the Config object. 00433 * @param modules The list of the IMEngine modules to be loaded. 00434 */ 00435 CommonBackEnd (const ConfigPointer &config, 00436 const std::vector<String> &modules); 00437 00438 virtual ~CommonBackEnd (); 00439 }; 00440 00441 } // namespace scim 00442 00443 #endif //__SCIM_BACKEND_H 00444 00445 /* 00446 vi:ts=4:nowrap:ai:expandtab 00447 */