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

scim_frontend.h

Go to the documentation of this file.
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 */

Generated on Fri May 7 17:27:25 2004 for scim by doxygen 1.3.6