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

scim_backend.h

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

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