Newer
Older
* libpyzy - The Chinese PinYin and Bopomofo conversion library.
*
* Copyright (c) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
*
* 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.1 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 library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
* USA
/**
* \brief Converts Pinyin / Bopomofo characters to phrases.
*
* Takes PinYin / Bopomofo characters and convert it to phrases.
* This class provides following methods.
* - Context manipulation methods like insert(), removeCharBefore(), ...
* - Getters of input / preedit / candidates / cursor / ...
* - Getters / Setters of some conversion options.
*
* To use this class, you should call InputContext::init() at first and
* InputContext::finalize() at last.
*/
#ifndef __PYZY_INPUT_CONTEXT_H_
#define __PYZY_INPUT_CONTEXT_H_
#include <string>
#include <vector>
namespace PyZy {
/**
* \brief An enum to represent a candidate type.
*/
/** Candidate from a system dictionary. */
/** Candidate from a user input. */
/** Candidate from a special phrase. */
/**
* \brief Contains a candidate data.
*/
/**
* \brief Pinyin / Bopomofo conversion class.
*
* This class is a factory class. You call a create() method and you get a
* pointer of the instance. You should delete it yourself.
* If some context are modified, you can get a nortification through Observer
* instance.
*/
/**
* \brief Virtual destructor.
*/
/**
* \brief Observer class of the InputContext.
*
* You override this class and pass it to InputContext::create, and you
* can get a nortification as a callback through this instance when some
* context are modified.
*/
class Observer {
public:
virtual ~Observer () { }
/**
* \brief Notifies a commit text.
* @param context InputContext instance which triggered this method.
* @param commit_text Commited text.
*
* This method is triggered by InputContext when conversion result
* is commited.
*/
virtual void commitText (const InputContext * context,
const std::string &commit_text) = 0;
/**
* \brief Notifies preedit text is changed.
* @param context InputContext instance which triggered this method.
*
* This method is triggered by InputContext when preedit text is
* changed.
*/
virtual void preeditTextChanged (const InputContext * context) = 0;
/**
* \brief Notifies auxiliary text is changed.
* @param context InputContext instance which triggered this method.
*
* This method is triggered by InputContext when auxiliary text is
* changed.
*/
virtual void auxiliaryTextChanged (const InputContext * context) = 0;
/**
* \brief Notifies candidates are changed.
* @param context InputContext instance which triggered this method.
*
* This method is triggered by InputContext when candidates are
* changed.
*/
virtual void candidatesChanged (const InputContext * context) = 0;
/**
* \brief Input text type.
*/
/** Input text is double pinyin. */
/**
* \brief Commit type.
*/
/** Commits a input text directly. */
/** Commits a selected text and rest input text. */
/** Commits a selected text, focused conversion text and rest text. */
/**
* \brief PropertyName
*/
/**
* Conversion option
* @see PyZyConst.h
*
* Default value is PINYIN_INCORRECT_PINYIN | PINYIN_CORRECT_ALL |
* PYZY_FUZZY_ALL
*/
/**
* \brief Double pinyin schema
* @see PyZyConst.h
*
* Default value is DOUBLE_PINYIN_KEYBOARD_MSPY.
*/
/**
* \brief Bopomofo schema
* @see PyZyConst.h
*
* Default value is BOPOMOFO_KEYBOARD_STANDARD.
*/
/**
* \brief Uses special phrase.
* Default value is true.
*/
/**
* \brief Uses simplified chinese character.
* Default value is true.
*/
/**
* \brief Appends a new character on cursor position.
* @param ch Input character. It should be ASCII characters.
* @return true if succeed.
*
* Appends a new character. This method fails if there are too many
* characters or invalid character is input.
*/
/**
* \brief Fixes the conversion result.
* @param type Commit type.
* @see CommitType
*
* Fixes the conversion result according to CommitType and resets the
* context.
*/
virtual void commit (CommitType type = TYPE_CONVERTED) = 0;
/**
* \brief Resets the context.
*/
/**
* \brief Moves a cursor to right input character.
* @return true if cursor is moved.
*/
/**
* \brief Moves a cursor to left input character.
* @return true if cursor is moved.
*/
/**
* \brief Moves a cursor to left chinese character.
* @return true if cursor is moved.
* @see moveCursorToEnd
*
* Currently text after a cursor is not converted and it is assumed as one
* chinese character. So this method is same as moveCursorToEnd.
*/
/**
* \brief Moves a cursor to right chinese character.
* @return true if cursor is moved.
*/
/**
* \brief Moves a cursor to the beginning of the the input text.
* @return true if cursor is moved.
*/
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
/**
* \brief Removes a input character before a cursor.
* @return true if a character is removed.
*/
virtual bool removeCharBefore (void) = 0;
/**
* \brief Removes a input character after a cursor.
* @return true if a character is removed.
*/
virtual bool removeCharAfter (void) = 0;
/**
* \brief Removes a chinese character before a cursor.
* @return true if a character is removed.
*/
virtual bool removeWordBefore (void) = 0;
/**
* \brief Removes a chinese character after a cursor.
* @return true if a character is removed.
*
* Currently text after a cursor is not converted and it is assumed as one
* chinese character. So this method removes all text after a cursor.
*/
virtual bool removeWordAfter (void) = 0;
/**
* \brief Moves a cursor to the end of the the input text.
* @return true if cursor is moved.
*/
/**
* \brief Selects a candidate and converts a rest text.
* @param index Index of the candidate. (0-origin)
* @return true if it takes valid index.
* @see commit
*
* If there are no rest text after select, this method triggeres commit.
*/
virtual bool selectCandidate (size_t index) = 0;
/**
* \brief Focuses a candidate.
* @param index Index of the candidate. (0-origin)
* @return true if it takes valid index.
*/
virtual bool focusCandidate (size_t index) = 0;
/**
* \brief Focuses a previous candidate.
* @param index Index of the candidate. (0-origin)
* @return true if focused index is changed.
*/
/**
* \brief Focuses a next candidate.
* @param index Index of the candidate. (0-origin)
* @return true if there are some candidates after the focused candidate;
* false otherwise.
*/
/**
* \brief Resets a user input history of the candidate.
* @param index Index of the candidate. (0-origin)
* @return true if it takes valid index.
*/
virtual bool resetCandidate (size_t index) = 0;
/**
* \brief Unselects a selected text.
* @return true if there are some selected text.
*/
/**
* \brief Checks the candidate is exist or not.
* @param index Index of the candidate. (0-origin)
* @return true if the candidate is exist.
* @see getPreparedCandidatesSize
*
* This method may update prepared
* candidates size.
*/
virtual bool hasCandidate (size_t index) = 0;
/**
* \brief Gets the candidate if exists.
* @param index Index of the candidate. (0-origin)
* @param output A candidate which is got.
* @return true if the candidate is exist.
* @see getPreparedCandidatesSize
*
* This method may update prepared
* candidates size.
*/
virtual bool getCandidate (size_t index, Candidate & output) = 0;
/**
* \brief Gets a already prepared candidates size.
* @return Prepared candidates size.
*
* To avoid a performance issue, this library prepares candidates on demand.
* This method returns a size of candidates which are already prepared.
*/
virtual size_t getPreparedCandidatesSize () const = 0;
/**
* \brief Initializes a InputContext class.
*
* You should call it at first.
*/
/**
* \brief Initializes a InputContext class.
* @param user_data_dir Directory which stores a user data.
*
* Specifies a directory to stores user data.
* You should call it at first.
*/
static void init (const std::string & user_data_dir);
/**
* \brief Finalizes a InputContext class.
*
* You should call it at last.
*/
/**
* \brief Creates a new InputContext instance.
* @param type The type of the input.
* @param observer Observer to get a notification from the InputContext
* instance.
* @return instance of the InputContext.
*
* You should take responsibility for deleting the instance.
*/
static InputContext * create (InputContext::InputType type,
/**
* \brief Returns a input text.
* @return input text.
*/
virtual const std::string & inputText () const = 0;
/**
* \brief Returns a selected text.
* @return selected text.
*/
virtual const std::string & selectedText (void) const = 0;
/**
* \brief Returns a conversion text.
* @return conversion text.
*/
virtual const std::string & conversionText (void) const = 0;
/**
* \brief Returns a rest text.
* @return rest text.
*/
virtual const std::string & restText (void) const = 0;
/**
* \brief Returns a auxiliary text.
* @return auxiliary text.
*/
virtual const std::string & auxiliaryText (void) const = 0;
/**
* \brief Returns a cursor position from the beginning of the input text.
* @return cursor position.
*/
virtual unsigned int cursor () const = 0;
/**
* \brief Returns a index of the focused candidate.
* @return index of the focused candidate. (0-origin)
*/
virtual unsigned int focusedCandidate () const = 0;
/**
* \brief Gets property of the context.
* @param name you want to get.
* @return value of the property.
*/
virtual Variant getProperty (PropertyName name) const = 0;
/**
* \brief Sets property of the context.
* @param name you want to get.
* @variant value of the property.
* @return true if the value is set successfully.
*/
virtual bool setProperty (PropertyName name, const Variant &variant)= 0;
#endif // __PYZY_INPUT_CONTEXT_H_