Your IP : 216.73.216.48
/** @file scim_frontend.h
* @brief Defines scim::FrontEndBase interface.
*
*/
/*
* Smart Common Input Method
*
* Copyright (c) 2002-2005 James Su <suzhe@tsinghua.org.cn>
*
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307 USA
*
* $Id: scim_frontend.h,v 1.42 2005/10/06 18:02:06 liuspider Exp $
*/
#ifndef __SCIM_FRONTEND_H
#define __SCIM_FRONTEND_H
namespace scim {
/**
* @addtogroup FrontEnd
* The base classes for FrontEnd modules.
* @{
*/
/**
* @brief An exception class to hold FrontEnd related errors.
*
* scim::FrontEndBase and its derived classes must throw
* scim::FrontEndError object when error.
*/
class FrontEndError: public Exception
{
public:
FrontEndError (const String& what_arg)
: Exception (String("scim::FrontEnd: ") + what_arg) { }
};
class FrontEndBase;
/**
* @typedef typedef Pointer <FrontEndBase> FrontEndPointer;
*
* A smart pointer for scim::FrontEndBase and its derived classes.
*/
typedef Pointer <FrontEndBase> FrontEndPointer;
/**
* @brief The base class to implement the FrontEnd objects.
*
* FrontEnd is an interface between IMEngineFactory/IMEngineInstance objects
* and the user applications. It forward the user requests to
* IMEngineFactory/IMEngineInstance objects, and handle the requests sent back.
*/
class FrontEndBase : public ReferencedObject
{
class FrontEndBaseImpl;
FrontEndBaseImpl *m_impl;
friend class FrontEndBaseImpl;
public:
/**
* @brief Constructor.
* @param backend A BackEnd object which holds all IMEngineFactory objects.
*/
FrontEndBase (const BackEndPointer &backend);
/**
* @brief Virtual destructor.
*/
virtual ~FrontEndBase ();
protected:
/**
* @name functions can be used by derived classes.
*
* @{
*/
/**
* @brief Get the IMEngine factories list for specific encoding
*
* @param uuids the vector to store the factories' uuids which
* support the encoding.
* @param encoding the encoding to be queried. If empty,
* all IMEngine factories will be returned.
*
* @return the number of IMEngine factories found.
*/
uint32 get_factory_list_for_encoding (std::vector<String> &uuids, const String &encoding) const;
/**
* @brief Get the IMEngine factories list for specific language
*
* @param uuids the vector to store the factories' uuids which
* support the encoding.
* @param language the language to be queried. If empty,
* all IMEngine factories will be returned.
*
* @return the number of IMEngine factories found.
*/
uint32 get_factory_list_for_language (std::vector<String> &uuids, const String &language) const;
/**
* @brief Get the default IMEngineFactory UUID for a specific language and encoding.
*
* @param language the language to be queried.
* @param encoding the encoding to be queried, if empty then don't match encoding.
*
* @return the UUID of the default IMEngineFactory for this language.
*/
String get_default_factory (const String &language, const String &encoding) const;
/**
* @brief Set the default IMEngineFactory for a specific language.
*
* @param language the language to be set.
* @param uuid the uuid of the default IMEngineFactory for this language.
*/
void set_default_factory (const String &language, const String &uuid);
/**
* @brief Get the next IMEngineFactory for a specific language and encoding.
*
* @param language the language to be queried, if empty then don't match language.
* @param encoding the encoding to be queried, if empty then don't match encoding.
* @param cur_uuid the UUID of current IMEngineFactory.
*
* @return the UUID of the next IMEngineFactory for this language and encoding
* corresponding to the current IMEngineFactory.
*/
String get_next_factory (const String &language, const String &encoding, const String &cur_uuid) const;
/**
* @brief Get the previous IMEngineFactory for a specific language and encoding.
*
* @param language the language to be queried, if empty then don't match language.
* @param encoding the encoding to be queried, if empty then don't match encoding.
* @param cur_uuid the UUID of current IMEngineFactory.
*
* @return the UUID of the previous IMEngineFactory for this language and encoding
* corresponding to the current IMEngineFactory.
*/
String get_previous_factory (const String &language, const String &encoding, const String &cur_uuid) const;
/**
* @brief get the name of an IMEngine factory.
*
* @param uuid the uuid of the IMEngine factory
* @return the name of the IMEngine factory.
*/
WideString get_factory_name (const String &uuid) const;
/**
* @brief get the authors info of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return the authors info of the IMEngine factory.
*/
WideString get_factory_authors (const String &uuid) const;
/**
* @brief get the credits info of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return the credits info of the IMEngine factory.
*/
WideString get_factory_credits (const String &uuid) const;
/**
* @brief get the help info of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return the help info of the IMEngine factory.
*/
WideString get_factory_help (const String &uuid) const;
/**
* @brief get the icon file of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return the icon file name of the IMEngine factory.
*/
String get_factory_icon_file (const String &uuid) const;
/**
* @brief get the supported locales of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return a comma separated list of the supported locales.
*/
String get_factory_locales (const String &uuid) const;
/**
* @brief get the language of an IMEngine factory.
* @param uuid the uuid of the IMEngine factory
* @return the language of this IMEngine factory.
*/
String get_factory_language (const String &uuid) const;
/**
* @brief Check if an IMEngine factory is valid and the given encoding is supported by it.
*
* @param uuid The uuid of the IMEngine factory to be checked.
* @param encoding The encoding should be supported by the factory.
* @return true if the factory is valid and the given encoding is supported.
*/
bool validate_factory (const String &uuid, const String &encoding = String ("")) const;
/**
* @brief get all locales supported by BackEnd.
* @return a comman separated list of all supported locales.
*/
String get_all_locales () const;
// IMEngine instance related functions.
/**
* @brief create a new IMEngine instance for specific encoding.
*
* @param sf_uuid the IMEngineFactory UUID.
* @param encoding the encoding to be used.
*
* @return the newly created IMEngine instance id, -1 means error occurred.
*/
int new_instance (const String &sf_uuid, const String &encoding);
/**
* @brief replace an IMEngine instance by a new instance created by another factory.
*
* This function is used to change the input method for an input context on the fly.
*
* @param si_id the IMEngine instance to be replaced.
* @param sf_uuid the new IMEngine factory to be used.
* @return true if success.
*/
bool replace_instance (int si_id, const String &sf_uuid);
/**
* @brief delete an IMEngine instance according to its id.
* @param id the id of the IMEngine instance to be deleted.
* @return true if success, false if there is no such instance.
*/
bool delete_instance (int id);
/**
* @brief delete all IMEngine instances.
*
* This function should be called just before quitting the FrontEnd.
*/
void delete_all_instances ();
/**
* @brief get the factory uuid of this instance.
* @param id the IMEngine instance id.
* @return the factory uuid of this instance.
*/
String get_instance_uuid (int id) const;
/**
* @brief get the working encoding of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the working encoding of this IMEngine instance.
*/
String get_instance_encoding (int id) const;
/**
* @brief get the name of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the name of this IMEngine instance,
* aka. the name of its factory.
*/
WideString get_instance_name (int id) const;
/**
* @brief get the authors info of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the authors info of this IMEngine instance,
* aka. the authors of its factory.
*/
WideString get_instance_authors (int id) const;
/**
* @brief get the credits info of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the credits info of this IMEngine instance,
* aka. the credits of its factory.
*/
WideString get_instance_credits (int id) const;
/**
* @brief get the help of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the help of this IMEngine instance,
* aka. the help of its factory.
*/
WideString get_instance_help (int id) const;
/**
* @brief get the icon file of an IMEngine instance.
* @param id the IMEngine instance id.
* @return the icon file name of this IMEngine instance.
*/
String get_instance_icon_file (int id) const;
/**
* @brief process a key event using specific IMEngine instance.
* @param id the IMEngine instance id.
* @param key the key event to be processed.
* @return true if the event was processed successfully,
* false if the event was not processed and should
* be forward to the client application.
*/
bool process_key_event (int id, const KeyEvent& key) const;
/**
* @brief let a specific IMEngine instance move its preedit caret.
* @param id the IMEngine instance id.
* @param pos the new preedit caret position.
*/
void move_preedit_caret (int id, unsigned int pos) const;
/**
* @brief let a specific IMEngine instance select a candidate in its current lookup table.
* @param id the IMEngine instance id.
* @param index the candidate index in current lookup table page to be selected.
*/
void select_candidate (int id, unsigned int index) const;
/**
* @brief update the page size of a specific IMEngine instance's lookup table.
* @param id the IMEngine instance id.
* @param page_size the new page size to be used.
*/
void update_lookup_table_page_size (int id, unsigned int page_size) const;
/**
* @brief Let a specific IMEngine instance flip its lookup table to the previous page.
*/
void lookup_table_page_up (int id) const;
/**
* @brief Let a specific IMEngine instance flip its lookup table to the previous page.
*/
void lookup_table_page_down (int id) const;
/**
* @brief reset a specific IMEngine instance.
* @param id the id of the IMEngine instance to be reset.
*/
void reset (int id) const;
/**
* @brief focus in a specific IMEngine instance.
* @param id the id of the IMEngine instance to be focused in.
*/
void focus_in (int id) const;
/**
* @brief focus out a specific IMEngine instance.
* @param id the id of the IMEngine instance to be focused out.
*/
void focus_out (int id) const;
/**
* @brief trigger a property of a specific IMEngine instance.
* @param id the id of the IMEngine instance.
* @param property the key of the property to be triggered.
*/
void trigger_property (int id, const String &property) const;
/**
* @brief let a specific IMEngine instance to process the events sent from a Helper process.
* @param id the id of the IMEngine instance.
* @param helper_uuid the uuid of the Helper process.
* @param trans the transaction which contains the events.
*/
void process_helper_event (int id, const String &helper_uuid, const Transaction &trans) const;
/**
* @brief let a specific IMEngine instance to update itself according to the capabilities of the client application.
* @param id the id of the IMEngine instance.
* @param cap the bitset of the capabilities which are supported by client.
*/
void update_client_capabilities (int id, unsigned int cap) const;
/**
* @}
*/
protected:
/**
* @name Virtual protected methods.
*
* The following methods should be implemented by derivation classes.
* these functions handle the real things.
*
* @{
*/
/**
* @brief show preedit string area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void show_preedit_string (int id);
/**
* @brief show aux string area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void show_aux_string (int id);
/**
* @brief show lookup table area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void show_lookup_table (int id);
/**
* @brief hide preedit string area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void hide_preedit_string (int id);
/**
* @brief hide aux string area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void hide_aux_string (int id);
/**
* @brief hide lookup table area for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void hide_lookup_table (int id);
/**
* @brief update the position of preedit caret for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param caret the new caret position.
*/
virtual void update_preedit_caret (int id, int caret);
/**
* @brief update the content of preedit string for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param str the new content of preedit string.
* @param attrs the string attributes.
*/
virtual void update_preedit_string (int id, const WideString & str, const AttributeList & attrs);
/**
* @brief update the content of aux string for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param str the new content of aux string.
* @param attrs the string attributes.
*/
virtual void update_aux_string (int id, const WideString & str, const AttributeList & attrs);
/**
* @brief update the content of lookup table for an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param table the new lookup table.
*/
virtual void update_lookup_table (int id, const LookupTable & table);
/**
* @brief commit a string to client for an IMEngine instance.
* @param id the id of the IMEngine instance to commit the string.
* @param str the string to be committed.
*/
virtual void commit_string (int id, const WideString & str);
/**
* @brief forward a keyevent to the client of an IMEngine instance.
* @param id the id of the IMEngine instance.
* @param key the key event to be forwarded.
*/
virtual void forward_key_event (int id, const KeyEvent & key);
/**
* @brief register all the properties of an IMEngine instance into this FrontEnd.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param properties the PropertyList contains all the properties of this IMEngine instance.
*/
virtual void register_properties (int id, const PropertyList & properties);
/**
* @brief update a property of an IMEngine instance.
* @param id the id of the IMEngine instance. It must have been focused in.
* @param property the Property to be updated.
*/
virtual void update_property (int id, const Property & property);
/**
* @brief generate a short beep.
* @param id the id of the IMEngine instance. It must have been focused in.
*/
virtual void beep (int id);
/**
* @brief start a Client Helper process.
*
* @param id the id of the IMEngine instance. It must have been focused in.
* @param helper_uuid The UUID of the Helper object.
*/
virtual void start_helper (int id, const String &helper_uuid);
/**
* @brief stop a Client Helper process.
*
* @param id the id of the IMEngine instance. It must have been focused in.
* @param helper_uuid The UUID of the Helper object.
*/
virtual void stop_helper (int id, const String &helper_uuid);
/**
* @brief send an events transaction to a Client Helper process.
*
* @param id the id of the IMEngine instance. It must have been focused in.
* @param helper_uuid The UUID of the Helper object.
* @param trans the transaction which contains events.
*/
virtual void send_helper_event (int id, const String &helper_uuid, const Transaction &trans);
/**
* @brief Retrieves context around the insertion point.
*
* Input methods typically want context in order to constrain
* input text based on existing text;
* this is important for languages such as Thai where
* only some sequences of characters are allowed.
*
* Unlike other signal activation actions, this action will return the result
* immediately.
*
* @param id the id of the IMEngine instance. It must have been focused in.
* @param text location to store the context string around the insertion point.
* @param cursor location to store index of the insertion cursor within @text.
* @param maxlen_before the maxmium length of context string to be retrieved
* before the cursor; -1 means unlimited.
* @param maxlen_after the maxmium length of context string to be retrieved
* after the cursor; -1 means unlimited.
*
* @return true if surrounding text was provided.
*/
virtual bool get_surrounding_text (int id, WideString &text, int &cursor, int maxlen_before, int maxlen_after);
/**
* @brief Ask the client to delete characters around the cursor position.
*
* In order to use this function, you should first call
* get_surrounding_text () to get the current context, and
* call this function immediately afterwards to make sure that you
* know what you are deleting. You should also account for the fact
* that even if the signal was handled, the input context might not
* have deleted all the characters that were requested to be deleted.
*
* @param id the id of the IMEngine instance. It must have been focused in.
* @param offset offset from cursor position in chars;
* a negative value means start before the cursor.
* @param len number of characters to delete.
*
* @return true if the signal was handled.
*/
virtual bool delete_surrounding_text (int id, int offset, int len);
/**
* @}
*/
public:
/**
* @brief init the frontend.
*
* This method must be implemented by derivation classes.
*/
virtual void init (int argc, char **argv) = 0;
/**
* @brief run the frontend.
*
* This method must be implemented by derivation classes.
*/
virtual void run () = 0;
};
/** @} */
} // namespace scim
#endif //__SCIM_FRONTEND_H
/*
vi:ts=4:nowrap:ai:expandtab
*/