Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | 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@tsinghua.org.cn>
00010  * Copyright (c) 2004 James Su <suzhe@turbolinux.com.cn>
00011  * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn>
00012  * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn>
00013  *
00014  *
00015  * This library is free software; you can redistribute it and/or
00016  * modify it under the terms of the GNU Lesser General Public
00017  * License as published by the Free Software Foundation; either
00018  * version 2 of the License, or (at your option) any later version.
00019  *
00020  * This library is distributed in the hope that it will be useful,
00021  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00022  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00023  * GNU Lesser General Public License for more details.
00024  *
00025  * You should have received a copy of the GNU Lesser General Public
00026  * License along with this program; if not, write to the
00027  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
00028  * Boston, MA  02111-1307  USA
00029  *
00030  * $Id: scim_frontend.h,v 1.29 2004/07/23 16:17:30 suzhe Exp $
00031  */
00032 
00033 #ifndef __SCIM_FRONTEND_H
00034 #define __SCIM_FRONTEND_H
00035 
00036 namespace scim {
00037 
00038 /**
00039  * @addtogroup FrontEnd
00040  * The base classes for FrontEnd modules.
00041  * @{
00042  */
00043 
00044 /**
00045  * @brief An exception class to hold FrontEnd related errors.
00046  *
00047  * scim::FrontEndBase and its derived classes must throw
00048  * scim::FrontEndError object when error.
00049  */
00050 class FrontEndError: public Exception
00051 {
00052 public:
00053     FrontEndError (const String& what_arg)
00054         : Exception (String("scim::FrontEnd: ") + what_arg) { }
00055 };
00056 
00057 class FrontEndBase;
00058 
00059 /**
00060  * @typedef typedef Pointer <FrontEndBase> FrontEndPointer;
00061  *
00062  * A smart pointer for scim::FrontEndBase and its derived classes.
00063  */
00064 typedef Pointer <FrontEndBase> FrontEndPointer;
00065 
00066 /**
00067  * @brief The base class to implement the FrontEnd objects.
00068  *
00069  * FrontEnd is an interface between IMEngineFactory/IMEngineInstance objects
00070  * and the user applications. It forward the user requests to
00071  * IMEngineFactory/IMEngineInstance objects, and handle the requests sent back.
00072  */
00073 class FrontEndBase : public ReferencedObject
00074 {
00075     class FrontEndBaseImpl;
00076 
00077     FrontEndBaseImpl *m_impl;
00078 
00079     friend class FrontEndBaseImpl;
00080 
00081 public:
00082     /**
00083      * @brief Constructor.
00084      * @param backend A BackEnd object which holds all IMEngineFactory objects.
00085      */
00086     FrontEndBase (const BackEndPointer &backend);
00087 
00088     /**
00089      * @brief Virtual destructor.
00090      */
00091     virtual ~FrontEndBase ();
00092 
00093 protected:
00094     /**
00095      * @name functions can be used by derived classes.
00096      * 
00097      * @{
00098      */
00099 
00100     /**
00101      * @brief Get the IMEngine factories list for specific encoding
00102      *
00103      * @param uuids    the vector to store the factories' uuids which
00104      *                 support the encoding.
00105      * @param encoding the encoding to be queried. If empty,
00106      *                 all IMEngine factories will be returned.
00107      *
00108      * @return the number of IMEngine factories found.
00109      */
00110     uint32 get_factory_list (std::vector<String> &uuids, const String &encoding) const;
00111 
00112     /**
00113      * @brief get the name of an IMEngine factory.
00114      *
00115      * @param uuid the uuid of the IMEngine factory
00116      * @return the name of the IMEngine factory.
00117      */
00118     WideString get_factory_name (const String &uuid) const;
00119 
00120     /**
00121      * @brief get the authors info of an IMEngine factory.
00122      * @param uuid the uuid of the IMEngine factory
00123      * @return the authors info of the IMEngine factory.
00124      */
00125     WideString get_factory_authors (const String &uuid) const;
00126 
00127     /**
00128      * @brief get the credits info of an IMEngine factory.
00129      * @param uuid the uuid of the IMEngine factory
00130      * @return the credits info of the IMEngine factory.
00131      */
00132     WideString get_factory_credits (const String &uuid) const;
00133 
00134     /**
00135      * @brief get the help info of an IMEngine factory.
00136      * @param uuid the uuid of the IMEngine factory
00137      * @return the help info of the IMEngine factory.
00138      */
00139     WideString get_factory_help (const String &uuid) const;
00140 
00141     /**
00142      * @brief get the icon file of an IMEngine factory.
00143      * @param uuid the uuid of the IMEngine factory
00144      * @return the icon file name of the IMEngine factory.
00145      */
00146     String get_factory_icon_file (const String &uuid) const;
00147 
00148     /**
00149      * @brief get the supported locales of an IMEngine  factory.
00150      * @param uuid the uuid of the IMEngine factory
00151      * @return a comma separated list of the supported locales.
00152      */
00153     String get_factory_locales (const String &uuid) const;
00154 
00155     /**
00156      * @brief get the language of an IMEngine factory.
00157      * @param uuid the uuid of the IMEngine factory
00158      * @return the language of this IMEngine factory.
00159      */
00160     String get_factory_language (const String &uuid) const;
00161 
00162     /**
00163      * @brief get all locales supported by BackEnd.
00164      * @return a comman separated list of all supported locales.
00165      */
00166     String get_all_locales () const;
00167 
00168     // IMEngine instance related functions.
00169 
00170     /**
00171      * @brief create a new IMEngine instance for specific encoding.
00172      *
00173      * @param sf_uuid the IMEngineFactory UUID.
00174      * @param encoding the encoding to be used.
00175      *
00176      * @return the newly created IMEngine instance id, -1 means error occurred.
00177      */
00178     int  new_instance (const String &sf_uuid, const String &encoding);
00179 
00180     /**
00181      * @brief replace an IMEngine  instance by a new instance created by another factory.
00182      *
00183      * This function is used to change the input method for an input context on the fly.
00184      *
00185      * @param si_id the IMEngine instance to be replaced.
00186      * @param sf_uuid the new IMEngine factory to be used.
00187      */
00188     bool replace_instance (int si_id, const String &sf_uuid);
00189 
00190     /**
00191      * @brief delete an IMEngine instance according to its id.
00192      * @param id the id of the IMEngine instance to be deleted.
00193      * @return true if success, false if there is no such instance.
00194      */
00195     bool delete_instance (int id);
00196 
00197     /**
00198      * @brief delete all IMEngine instances.
00199      *
00200      * This function should be called just before quitting the FrontEnd.
00201      */
00202     void delete_all_instances ();
00203 
00204     /**
00205      * @brief get the working encoding of an IMEngine instance.
00206      * @param id the IMEngine instance id.
00207      * @return the working encoding of this IMEngine instance.
00208      */
00209     String get_instance_encoding (int id) const;
00210 
00211     /**
00212      * @brief get the name of an IMEngine instance.
00213      * @param id the IMEngine instance id.
00214      * @return the name of this IMEngine instance,
00215      *         aka. the name of its factory.
00216      */
00217     WideString get_instance_name (int id) const;
00218 
00219     /**
00220      * @brief get the authors info of an IMEngine instance.
00221      * @param id the IMEngine instance id.
00222      * @return the authors info of this IMEngine instance,
00223      *         aka. the authors of its factory.
00224      */
00225     WideString get_instance_authors (int id) const;
00226 
00227     /**
00228      * @brief get the credits info of an IMEngine instance.
00229      * @param id the IMEngine instance id.
00230      * @return the credits info of this IMEngine instance,
00231      *         aka. the credits of its factory.
00232      */
00233     WideString get_instance_credits (int id) const;
00234 
00235     /**
00236      * @brief get the help of an IMEngine instance.
00237      * @param id the IMEngine instance id.
00238      * @return the help of this IMEngine instance,
00239      *         aka. the help of its factory.
00240      */
00241     WideString get_instance_help (int id) const;
00242 
00243     /**
00244      * @brief get the icon file of an IMEngine instance.
00245      * @param id the IMEngine instance id.
00246      * @return the icon file name of this IMEngine instance.
00247      */
00248     String get_instance_icon_file (int id) const;
00249 
00250     /**
00251      * @brief process a key event using specific IMEngine instance.
00252      * @param id the IMEngine instance id.
00253      * @param key the key event to be processed.
00254      * @return true if the event was processed successfully,
00255      *         false if the event was not processed and should
00256      *         be forward to the client application.
00257      */
00258     bool process_key_event (int id, const KeyEvent& key) const;
00259 
00260     /**
00261      * @brief let a specific IMEngine instance move its preedit caret.
00262      * @param id the IMEngine instance id.
00263      * @param pos the new preedit caret position.
00264      */
00265     void move_preedit_caret (int id, unsigned int pos) const;
00266 
00267     /**
00268      * @brief let a specific IMEngine instance select a candidate in its current lookup table.
00269      * @param id the IMEngine instance id.
00270      * @param index the candidate index in current lookup table page to be selected.
00271      */
00272     void select_candidate (int id, unsigned int index) const;
00273 
00274     /**
00275      * @brief update the page size of a specific IMEngine instance's lookup table.
00276      * @param id the IMEngine instance id.
00277      * @param page_size the new page size to be used.
00278      */
00279     void update_lookup_table_page_size (int id, unsigned int page_size) const;
00280 
00281     /**
00282      * @brief Let a specific IMEngine instance flip its lookup table to the previous page.
00283      */
00284     void lookup_table_page_up (int id) const;
00285 
00286     /**
00287      * @brief Let a specific IMEngine instance flip its lookup table to the previous page.
00288      */
00289     void lookup_table_page_down (int id) const;
00290 
00291     /**
00292      * @brief reset a specific IMEngine instance.
00293      * @param id the id of the IMEngine instance to be reset.
00294      */
00295     void reset (int id) const;
00296 
00297     /**
00298      * @brief focus in a specific IMEngine instance.
00299      * @param id the id of the IMEngine instance to be focused in.
00300      */
00301     void focus_in (int id) const;
00302 
00303     /**
00304      * @brief focus out a specific IMEngine instance.
00305      * @param id the id of the IMEngine instance to be focused out.
00306      */
00307     void focus_out (int id) const;
00308 
00309     /**
00310      * @brief trigger a property of a specific IMEngine instance.
00311      * @param id the id of the IMEngine instance.
00312      * @param property the key of the property to be triggered.
00313      */
00314     void trigger_property (int id, const String &property) const;
00315 
00316     /**
00317      * @}
00318      */
00319 
00320 protected:
00321     /**
00322      * @name Pure virtual protected methods.
00323      *
00324      * The following methods should be implemented by derivation classes.
00325      * these functions handle the real things.
00326      * 
00327      * @{
00328      */
00329  
00330     /**
00331      * @brief show preedit string area for an IMEngine instance.
00332      * @param id the id of the IMEngine instance. It must have been focused in.
00333      */
00334     virtual void show_preedit_string (int id) = 0;
00335 
00336     /**
00337      * @brief show aux string area for an IMEngine instance.
00338      * @param id the id of the IMEngine instance. It must have been focused in.
00339      */
00340     virtual void show_aux_string     (int id) = 0;
00341 
00342     /**
00343      * @brief show lookup table area for an IMEngine instance.
00344      * @param id the id of the IMEngine instance. It must have been focused in.
00345      */
00346     virtual void show_lookup_table   (int id) = 0;
00347 
00348     /**
00349      * @brief hide preedit string area for an IMEngine instance.
00350      * @param id the id of the IMEngine instance. It must have been focused in.
00351      */
00352     virtual void hide_preedit_string (int id) = 0;
00353 
00354     /**
00355      * @brief hide aux string area for an IMEngine instance.
00356      * @param id the id of the IMEngine instance. It must have been focused in.
00357      */
00358     virtual void hide_aux_string     (int id) = 0;
00359 
00360     /**
00361      * @brief hide lookup table area for an IMEngine instance.
00362      * @param id the id of the IMEngine instance. It must have been focused in.
00363      */
00364     virtual void hide_lookup_table   (int id) = 0;
00365 
00366     /**
00367      * @brief update the position of preedit caret for an IMEngine instance.
00368      * @param id the id of the IMEngine instance. It must have been focused in.
00369      * @param caret the new caret position.
00370      */
00371     virtual void update_preedit_caret  (int id, int caret) = 0;
00372 
00373     /**
00374      * @brief update the content of preedit string for an IMEngine instance.
00375      * @param id the id of the IMEngine instance. It must have been focused in.
00376      * @param str the new content of preedit string.
00377      * @param attrs the string attributes.
00378      */
00379     virtual void update_preedit_string (int id, const WideString & str, const AttributeList & attrs) = 0;
00380 
00381     /**
00382      * @brief update the content of aux string for an IMEngine instance.
00383      * @param id the id of the IMEngine instance. It must have been focused in.
00384      * @param str the new content of aux string.
00385      * @param attrs the string attributes.
00386      */
00387     virtual void update_aux_string     (int id, const WideString & str, const AttributeList & attrs) = 0;
00388 
00389     /**
00390      * @brief update the content of lookup table for an IMEngine instance.
00391      * @param id the id of the IMEngine instance. It must have been focused in.
00392      * @param table the new lookup table.
00393      */
00394     virtual void update_lookup_table   (int id, const LookupTable & table) = 0;
00395 
00396     /**
00397      * @brief commit a string to client for an IMEngine instance.
00398      * @param id the id of the IMEngine instance to commit the string.
00399      * @param str the string to be committed.
00400      */
00401     virtual void commit_string         (int id, const WideString & str) = 0;
00402 
00403     /**
00404      * @brief forward a keyevent to the client of an IMEngine instance.
00405      * @param id the id of the IMEngine instance.
00406      * @param key the key event to be forwarded.
00407      */
00408     virtual void forward_key_event      (int id, const KeyEvent & key) = 0;
00409 
00410     /**
00411      * @brief register all the properties of an IMEngine instance into this FrontEnd.
00412      * @param id the id of the IMEngine instance. It must have been focused in.
00413      * @param properties the PropertyList contains all the properties of this IMEngine instance.
00414      */
00415     virtual void register_properties   (int id, const PropertyList & properties) = 0;
00416 
00417     /**
00418      * @brief update a property of an IMEngine instance.
00419      * @param id the id of the IMEngine instance. It must have been focused in.
00420      * @param property the Property to be updated.
00421      */
00422     virtual void update_property       (int id, const Property & property) = 0;
00423 
00424     /**
00425      * @}
00426      */
00427 
00428 public:
00429     /**
00430      * @brief init the frontend.
00431      *
00432      * This method must be implemented by derivation classes.
00433      */
00434     virtual void init (int argc, char **argv) = 0;
00435 
00436     /**
00437      * @brief run the frontend.
00438      *
00439      * This method must be implemented by derivation classes.
00440      */
00441     virtual void run () = 0;
00442 };
00443 
00444 /** @} */
00445 
00446 } // namespace scim
00447 
00448 #endif //__SCIM_FRONTEND_H
00449 
00450 /*
00451 vi:ts=4:nowrap:ai:expandtab
00452 */

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