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