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

scim_imengine.h

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

Generated on Tue Apr 19 00:10:59 2005 for scim by  doxygen 1.4.1