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@turbolinux.com.cn> 00010 * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn> 00011 * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn> 00012 * 00013 * 00014 * This library is free software; you can redistribute it and/or 00015 * modify it under the terms of the GNU Lesser General Public 00016 * License as published by the Free Software Foundation; either 00017 * version 2 of the License, or (at your option) any later version. 00018 * 00019 * This library is distributed in the hope that it will be useful, 00020 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00021 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00022 * GNU Lesser General Public License for more details. 00023 * 00024 * You should have received a copy of the GNU Lesser General Public 00025 * License along with this program; if not, write to the 00026 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 00027 * Boston, MA 02111-1307 USA 00028 * 00029 * $Id: scim_frontend.h,v 1.23 2004/02/12 09:40:12 suzhe Exp $ 00030 */ 00031 00032 #ifndef __SCIM_FRONTEND_H 00033 #define __SCIM_FRONTEND_H 00034 00035 namespace scim { 00036 00037 /** 00038 * @addtogroup FrontEnd 00039 * The base classes for FrontEnd modules. 00040 * @{ 00041 */ 00042 00043 /** 00044 * @brief An exception class to hold FrontEnd related errors. 00045 * 00046 * scim::FrontEndBase and its derived classes must throw 00047 * scim::FrontEndError object when error. 00048 */ 00049 class FrontEndError: public Exception 00050 { 00051 public: 00052 FrontEndError (const String& what_arg) 00053 : Exception (String("scim::FrontEnd: ") + what_arg) { } 00054 }; 00055 00056 class FrontEndBase; 00057 00058 /** 00059 * @typedef typedef Pointer <FrontEndBase> FrontEndPointer; 00060 * 00061 * A smart pointer for scim::FrontEndBase and its derived classes. 00062 */ 00063 typedef Pointer <FrontEndBase> FrontEndPointer; 00064 00065 /** 00066 * @brief The base class to implement the FrontEnd objects. 00067 * 00068 * FrontEnd is an interface between ServerFactory/ServerInstance objects 00069 * and the user applications. It forward the user requests to 00070 * ServerFactory/ServerInstance objects, and handle the requests sent back. 00071 */ 00072 class FrontEndBase : public ReferencedObject 00073 { 00074 typedef std::vector <ServerInstancePointer> ServerInstanceRepository; 00075 typedef std::vector <ServerFactoryPointer> ServerFactoryRepository; 00076 00077 BackEndPointer m_backend; 00078 00079 ServerInstanceRepository m_server_instance_repository; 00080 ServerFactoryRepository m_server_factory_repository; 00081 00082 int m_server_instance_id_count; 00083 00084 public: 00085 /** 00086 * @brief Constructor. 00087 * @param backend A BackEnd object which holds all ServerFactory objects. 00088 */ 00089 FrontEndBase (const BackEndPointer &backend); 00090 00091 /** 00092 * @brief Virtual destructor. 00093 */ 00094 virtual ~FrontEndBase (); 00095 00096 private: 00097 /** 00098 * @name Slot functions. 00099 * These functions will be connected to the corresponding Signals 00100 * of the ServerInstance objects. 00101 * 00102 * @{ 00103 */ 00104 void slot_show_preedit_string (ServerInstanceBase * si); 00105 void slot_show_status_string (ServerInstanceBase * si); 00106 void slot_show_aux_string (ServerInstanceBase * si); 00107 void slot_show_lookup_table (ServerInstanceBase * si); 00108 00109 void slot_hide_preedit_string (ServerInstanceBase * si); 00110 void slot_hide_status_string (ServerInstanceBase * si); 00111 void slot_hide_aux_string (ServerInstanceBase * si); 00112 void slot_hide_lookup_table (ServerInstanceBase * si); 00113 00114 void slot_update_preedit_caret (ServerInstanceBase * si, int caret); 00115 void slot_update_preedit_string (ServerInstanceBase * si, const WideString & str, const AttributeList & attrs); 00116 void slot_update_status_string (ServerInstanceBase * si, const WideString & str, const AttributeList & attrs); 00117 void slot_update_aux_string (ServerInstanceBase * si, const WideString & str, const AttributeList & attrs); 00118 void slot_commit_string (ServerInstanceBase * si, const WideString & str); 00119 void slot_forward_keyevent (ServerInstanceBase * si, const KeyEvent & key); 00120 void slot_update_lookup_table (ServerInstanceBase * si, const LookupTable & table); 00121 00122 void slot_update_full_width_punctuation (ServerInstanceBase * si, bool full); 00123 void slot_update_full_width_letter (ServerInstanceBase * si, bool full); 00124 /** 00125 * @} 00126 */ 00127 00128 private: 00129 void query_server_factories (); 00130 00131 ServerFactoryPointer find_server_factory (const String &uuid) const; 00132 00133 ServerInstancePointer find_server_instance (int id) const; 00134 00135 void add_server_instance (const ServerInstancePointer &si); 00136 00137 void attach_server_instance (const ServerInstancePointer &si); 00138 00139 protected: 00140 /** 00141 * @name functions can be used by derived classes. 00142 * 00143 * @{ 00144 */ 00145 00146 /** 00147 * @brief Get the server factories list for specific encoding 00148 * 00149 * @param uuids the vector to store the factories' uuids which 00150 * support the encoding. 00151 * @param encoding the encoding to be queried. If empty, 00152 * all server factories will be returned. 00153 * 00154 * @return the number of server factories found. 00155 */ 00156 uint32 get_server_factory_list (std::vector<String> &uuids, const String &encoding) const; 00157 00158 /** 00159 * @brief get the name of a server factory. 00160 * 00161 * @param uuid the uuid of the server factory 00162 * @return the name of the server factory. 00163 */ 00164 WideString get_server_factory_name (const String &uuid) const; 00165 00166 /** 00167 * @brief get the authors info of a server factory. 00168 * @param uuid the uuid of the server factory 00169 * @return the authors info of the server factory. 00170 */ 00171 WideString get_server_factory_authors (const String &uuid) const; 00172 00173 /** 00174 * @brief get the credits info of a server factory. 00175 * @param uuid the uuid of the server factory 00176 * @return the credits info of the server factory. 00177 */ 00178 WideString get_server_factory_credits (const String &uuid) const; 00179 00180 /** 00181 * @brief get the help info of a server factory. 00182 * @param uuid the uuid of the server factory 00183 * @return the help info of the server factory. 00184 */ 00185 WideString get_server_factory_help (const String &uuid) const; 00186 00187 /** 00188 * @brief get the icon file of a server factory. 00189 * @param uuid the uuid of the server factory 00190 * @return the icon file name of the server factory. 00191 */ 00192 String get_server_factory_icon_file (const String &uuid) const; 00193 00194 /** 00195 * @brief get the supported locales of a server factory. 00196 * @param uuid the uuid of the server factory 00197 * @return a comma separated list of the supported locales. 00198 */ 00199 String get_server_factory_locales (const String &uuid) const; 00200 00201 /** 00202 * @brief get all locales supported by BackEnd. 00203 * @return a comman separated list of all supported locales. 00204 */ 00205 String get_all_locales () const; 00206 00207 // server instance related functions. 00208 00209 /** 00210 * @brief create a new server instance for specific encoding. 00211 * 00212 * @param sf_uuid the ServerFactory UUID. 00213 * @param encoding the encoding to be used. 00214 * 00215 * @return the newly created server instance id, -1 means error occurred. 00216 */ 00217 int new_server_instance (const String &sf_uuid, const String &encoding); 00218 00219 /** 00220 * @brief replace a server instance by a new instance created by another factory. 00221 * 00222 * This function is used to change the input method for an input context on the fly. 00223 * 00224 * @param si_id the server instance to be replaced. 00225 * @param sf_uuid the new server factory to be used. 00226 */ 00227 bool replace_server_instance (int si_id, const String &sf_uuid); 00228 00229 /** 00230 * @brief delete a server instance according to its id. 00231 * @param id the id of the server instance to be deleted. 00232 * @return true if success, false if there is no such instance. 00233 */ 00234 bool delete_server_instance (int id); 00235 00236 /** 00237 * @brief delete all server instances. 00238 * 00239 * This function should be called just before quitting the FrontEnd. 00240 */ 00241 void delete_all_server_instances (); 00242 00243 /** 00244 * @brief get the working encoding of a server instance. 00245 * @param id the server instance id. 00246 * @return the working encoding of this server instance. 00247 */ 00248 String get_server_instance_encoding (int id) const; 00249 00250 /** 00251 * @brief get the name of a server instance. 00252 * @param id the server instance id. 00253 * @return the name of this server instance, 00254 * aka. the name of its factory. 00255 */ 00256 WideString get_server_instance_name (int id) const; 00257 00258 /** 00259 * @brief get the authors info of a server instance. 00260 * @param id the server instance id. 00261 * @return the authors info of this server instance, 00262 * aka. the authors of its factory. 00263 */ 00264 WideString get_server_instance_authors (int id) const; 00265 00266 /** 00267 * @brief get the credits info of a server instance. 00268 * @param id the server instance id. 00269 * @return the credits info of this server instance, 00270 * aka. the credits of its factory. 00271 */ 00272 WideString get_server_instance_credits (int id) const; 00273 00274 /** 00275 * @brief get the help of a server instance. 00276 * @param id the server instance id. 00277 * @return the help of this server instance, 00278 * aka. the help of its factory. 00279 */ 00280 WideString get_server_instance_help (int id) const; 00281 00282 /** 00283 * @brief get the icon file of a server instance. 00284 * @param id the server instance id. 00285 * @return the icon file name of this server instance. 00286 */ 00287 String get_server_instance_icon_file (int id) const; 00288 00289 /** 00290 * @brief process a key event using specific server instance. 00291 * @param id the server instance id. 00292 * @param key the key event to be processed. 00293 * @return true if the event was processed successfully, 00294 * false if the event was not processed and should 00295 * be forward to the client application. 00296 */ 00297 bool process_key_event (int id, const KeyEvent& key) const; 00298 00299 /** 00300 * @brief let a specific server instance move its preedit caret. 00301 * @param id the server instance id. 00302 * @param pos the new preedit caret position. 00303 */ 00304 void move_preedit_caret (int id, unsigned int pos) const; 00305 00306 /** 00307 * @brief let a specific server instance select an item in its current lookup table. 00308 * @param id the server instance id. 00309 * @param item the lookup table item to be selected. 00310 */ 00311 void select_lookup_table (int id, unsigned int item) const; 00312 00313 /** 00314 * @brief update the page size of a specific server instance's lookup table. 00315 * @param id the server instance id. 00316 * @param page_size the new page size to be used. 00317 */ 00318 void update_lookup_table_page_size (int id, unsigned int page_size) const; 00319 00320 /** 00321 * @brief reset a specific server instance. 00322 * @param id the id of the server instance to be reset. 00323 */ 00324 void reset_server_instance (int id) const; 00325 00326 /** 00327 * @brief focus in a specific server instance. 00328 * @param id the id of the server instance to be focused in. 00329 */ 00330 void focus_in_server_instance (int id) const; 00331 00332 /** 00333 * @brief focus out a specific server instance. 00334 * @param id the id of the server instance to be focused out. 00335 */ 00336 void focus_out_server_instance (int id) const; 00337 00338 /** 00339 * @brief let a specific server instance toggle its full/half width punctuation state. 00340 * @param id the server instance id. 00341 */ 00342 void toggle_full_width_punctuation (int id) const; 00343 00344 /** 00345 * @brief let a specific server instance toggle its full/half width letter state. 00346 * @param id the server instance id. 00347 */ 00348 void toggle_full_width_letter (int id) const; 00349 00350 /** 00351 * @brief let a specific server instance toggle its input status. 00352 * @param id the server instance id. 00353 */ 00354 void toggle_input_status (int id) const; 00355 00356 /** 00357 * @} 00358 */ 00359 00360 protected: 00361 /** 00362 * @name Pure virtual protected methods. 00363 * 00364 * The following methods should be implemented by derivation classes. 00365 * these functions handle the real things. 00366 * 00367 * @{ 00368 */ 00369 00370 /** 00371 * @brief show preedit string area for a server instance. 00372 * @param id the id of the server instance, it must be focused in. 00373 */ 00374 virtual void show_preedit_string (int id) = 0; 00375 00376 /** 00377 * @brief show status string area for a server instance. 00378 * @param id the id of the server instance, it must be focused in. 00379 */ 00380 virtual void show_status_string (int id) = 0; 00381 00382 /** 00383 * @brief show aux string area for a server instance. 00384 * @param id the id of the server instance, it must be focused in. 00385 */ 00386 virtual void show_aux_string (int id) = 0; 00387 00388 /** 00389 * @brief show lookup table area for a server instance. 00390 * @param id the id of the server instance, it must be focused in. 00391 */ 00392 virtual void show_lookup_table (int id) = 0; 00393 00394 /** 00395 * @brief hide preedit string area for a server instance. 00396 * @param id the id of the server instance, it must be focused in. 00397 */ 00398 virtual void hide_preedit_string (int id) = 0; 00399 00400 /** 00401 * @brief hide status string area for a server instance. 00402 * @param id the id of the server instance, it must be focused in. 00403 */ 00404 virtual void hide_status_string (int id) = 0; 00405 00406 /** 00407 * @brief hide aux string area for a server instance. 00408 * @param id the id of the server instance, it must be focused in. 00409 */ 00410 virtual void hide_aux_string (int id) = 0; 00411 00412 /** 00413 * @brief hide lookup table area for a server instance. 00414 * @param id the id of the server instance, it must be focused in. 00415 */ 00416 virtual void hide_lookup_table (int id) = 0; 00417 00418 /** 00419 * @brief update the position of preedit caret for a server instance. 00420 * @param id the id of the server instance, it must be focused in. 00421 * @param caret the new caret position. 00422 */ 00423 virtual void update_preedit_caret (int id, int caret) = 0; 00424 00425 /** 00426 * @brief update the content of preedit string for a server instance. 00427 * @param id the id of the server instance, it must be focused in. 00428 * @param str the new content of preedit string. 00429 * @param attrs the string attributes. 00430 */ 00431 virtual void update_preedit_string (int id, const WideString & str, const AttributeList & attrs) = 0; 00432 00433 /** 00434 * @brief update the content of status string for a server instance. 00435 * @param id the id of the server instance, it must be focused in. 00436 * @param str the new content of status string. 00437 * @param attrs the string attributes. 00438 */ 00439 virtual void update_status_string (int id, const WideString & str, const AttributeList & attrs) = 0; 00440 00441 /** 00442 * @brief update the content of aux string for a server instance. 00443 * @param id the id of the server instance, it must be focused in. 00444 * @param str the new content of aux string. 00445 * @param attrs the string attributes. 00446 */ 00447 virtual void update_aux_string (int id, const WideString & str, const AttributeList & attrs) = 0; 00448 00449 /** 00450 * @brief update the content of lookup table for a server instance. 00451 * @param id the id of the server instance, it must be focused in. 00452 * @param table the new lookup table. 00453 */ 00454 virtual void update_lookup_table (int id, const LookupTable & table) = 0; 00455 00456 /** 00457 * @brief commit a string to client for a server instance. 00458 * @param id the id of the server instance to commit the string. 00459 * @param str the string to be committed. 00460 */ 00461 virtual void commit_string (int id, const WideString & str) = 0; 00462 00463 /** 00464 * @brief forward a keyevent to the client of a server instance. 00465 * @param id the id of the server instance, it must be focused in. 00466 * @param key the key event to be forwarded. 00467 */ 00468 virtual void forward_keyevent (int id, const KeyEvent & key) = 0; 00469 00470 /** 00471 * @brief update the full width punctuation status for a server instance. 00472 * @param id the id of the server instance, it must be focused in. 00473 * @param full indicates the punctuation input status, 00474 * true = full width, false = half width. 00475 */ 00476 virtual void update_full_width_punctuation (int id, bool full) = 0; 00477 00478 /** 00479 * @brief update the full width letter status for a server instance. 00480 * @param id the id of the server instance, it must be focused in. 00481 * @param full indicates the letter input status, 00482 * true = full width, false = half width. 00483 */ 00484 virtual void update_full_width_letter (int id, bool full) = 0; 00485 00486 /** 00487 * @} 00488 */ 00489 00490 public: 00491 /** 00492 * @brief init the frontend. 00493 * 00494 * This method must be implemented by derivation classes. 00495 */ 00496 virtual void init (int argc, char **argv) = 0; 00497 00498 /** 00499 * @brief run the frontend. 00500 * 00501 * This method must be implemented by derivation classes. 00502 */ 00503 virtual void run () = 0; 00504 }; 00505 00506 /** @} */ 00507 00508 } // namespace scim 00509 00510 #endif //__SCIM_FRONTEND_H 00511 00512 /* 00513 vi:ts=4:nowrap:ai:expandtab 00514 */