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

scim_server.h

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

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