PyZyInputContext.h

/* vim:set et ts=4 sts=4:
 *
 * 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 {

class Variant;

/**
 * \brief An enum to represent a candidate type.
 */
enum CandidateType {
    /** Candidate from a system dictionary. */
    NORMAL_PHRASE,
    /** Candidate from a user input. */
    USER_PHRASE,
    /** Candidate from a special phrase. */
    SPECIAL_PHRASE,
};

/**
 * \brief Contains a candidate data.
 */
struct Candidate {
    /** Text of a candidate */
    std::string text;
    /** Type of a candidate */
    CandidateType type;
};

/**
 * \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.
 */
class InputContext {
public:
    /**
     * \brief Virtual destructor.
     */
    virtual ~InputContext (void) { }

    /**
     * \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.
     */
    enum InputType {
        /** Input text is full pinyin. */
        FULL_PINYIN,
        /** Input text is double pinyin. */
        DOUBLE_PINYIN,
        /** Input text is bopomofo. */
        BOPOMOFO,
    };

    /**
     * \brief Commit type.
     */
    enum CommitType {
        /** Commits a input text directly. */
        TYPE_RAW,
        /** Commits a selected text and rest input text. */
        TYPE_PHONETIC,
        /** Commits a selected text, focused conversion text and rest text. */
        TYPE_CONVERTED,
    };

    /**
     * \brief PropertyName
     */
    enum PropertyName {
        /**
         * Conversion option
         * @see PyZyConst.h
         *
         * Default value is PINYIN_INCORRECT_PINYIN | PINYIN_CORRECT_ALL |
         * PYZY_FUZZY_ALL
         */
        PROPERTY_CONVERSION_OPTION,
        /**
         * \brief Double pinyin schema
         * @see PyZyConst.h
         *
         * Default value is DOUBLE_PINYIN_KEYBOARD_MSPY.
         */
        PROPERTY_DOUBLE_PINYIN_SCHEMA,
        /**
         * \brief Bopomofo schema
         * @see PyZyConst.h
         *
         * Default value is BOPOMOFO_KEYBOARD_STANDARD.
         */
        PROPERTY_BOPOMOFO_SCHEMA,
        /**
         * \brief Uses special phrase.
         * Default value is true.
        */
        PROPERTY_SPECIAL_PHRASE,
        /**
         * \brief Uses simplified chinese character.
         * Default value is true.
         */
        PROPERTY_MODE_SIMP,
    };

    /**
     * \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.
     */
    virtual bool insert (char ch) = 0;

    /**
     * \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.
     */
    virtual void reset (void) = 0;

    /**
     * \brief Moves a cursor to right input character.
     * @return true if cursor is moved.
     */
    virtual bool moveCursorRight (void) = 0;

    /**
     * \brief Moves a cursor to left input character.
     * @return true if cursor is moved.
     */
    virtual bool moveCursorLeft (void) = 0;

    /**
     * \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.
     */
    virtual bool moveCursorRightByWord (void) = 0;

    /**
     * \brief Moves a cursor to right chinese character.
     * @return true if cursor is moved.
     */
    virtual bool moveCursorLeftByWord (void) = 0;

    /**
     * \brief Moves a cursor to the beginning of the the input text.
     * @return true if cursor is moved.
     */
    virtual bool moveCursorToBegin (void) = 0;

    /**
     * \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.
     */
    virtual bool moveCursorToEnd (void) = 0;

    /**
     * \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.
     */
    virtual bool focusCandidatePrevious (void) = 0;

    /**
     * \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.
     */
    virtual bool focusCandidateNext (void) = 0;

    /**
     * \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.
     */
    virtual bool unselectCandidates () = 0;

    /**
     * \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.
     */
    static void init ();

    /**
     * \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.
     */
    static void finalize ();

    /**
     * \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,
                                  InputContext::Observer * observer);

    /**
     * \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;
};

}; // namespace PyZy

#endif  // __PYZY_INPUT_CONTEXT_H_