Home | History | Annotate | Download | only in openwnn
      1 /*
      2  * Copyright (C) 2008,2009  OMRON SOFTWARE Co., Ltd.
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package jp.co.omronsoft.openwnn;
     18 
     19 import android.content.SharedPreferences;
     20 
     21 /**
     22  * The interface of the text converter accessed from OpenWnn.
     23  * <br>
     24  * The realization class of this interface should be an singleton class.
     25  *
     26  * @author Copyright (C) 2009, OMRON SOFTWARE CO., LTD.  All Rights Reserved.
     27  */
     28 public interface WnnEngine {
     29     /*
     30      * DEFINITION OF CONSTANTS
     31      */
     32     /** The identifier of the learning dictionary */
     33     public static final int DICTIONARY_TYPE_LEARN = 1;
     34     /** The identifier of the user dictionary */
     35     public static final int DICTIONARY_TYPE_USER  = 2;
     36 
     37     /*
     38      * DEFINITION OF METHODS
     39      */
     40     /**
     41      * Initialize parameters.
     42      */
     43     public void init();
     44 
     45     /**
     46      * Close the converter.
     47      * <br>
     48      *
     49      * OpenWnn calls this method when it is destroyed.
     50      */
     51     public void close();
     52 
     53     /**
     54      * Predict words/phrases.
     55      * <br>
     56      * @param text      The input string
     57      * @param minLen    The minimum length of a word to predict (0  : no limit)
     58      * @param maxLen    The maximum length of a word to predict (-1 : no limit)
     59      * @return          Plus value if there are candidates; 0 if there is no candidate; minus value if a error occurs.
     60      */
     61     public int predict(ComposingText text, int minLen, int maxLen);
     62 
     63     /**
     64      * Convert a string.
     65      * <br>
     66      * This method is used to consecutive/single clause convert in
     67      * Japanese, Pinyin to Kanji convert in Chinese, Hangul to Hanja
     68      * convert in Korean, etc.
     69      *
     70      * The result of conversion is set into the layer 2 in the {@link ComposingText}.
     71      * To get other candidates of each clause, call {@link #makeCandidateListOf(int)}.
     72      *
     73      * @param text      The input string
     74      * @return      Plus value if there are candidates; 0 if there is no candidate; minus value if a error occurs.
     75      */
     76     public int convert(ComposingText text);
     77 
     78     /**
     79      * Search words from the dictionaries.
     80      * <br>
     81      * @param key       The search key (stroke)
     82      * @return      Plus value if there are candidates; 0 if there is no candidate; minus value if a error occurs.
     83      */
     84     public int searchWords(String key);
     85 
     86     /**
     87      * Search words from the dictionaries.
     88      * <br>
     89      * @param word      A word to search
     90      * @return          Plus value if there are candidates; 0 if there is no candidate; minus value if a error occurs.
     91      */
     92     public int searchWords(WnnWord word);
     93 
     94     /**
     95      * Get a candidate.
     96      * <br>
     97      * After {@link #predict(ComposingText, int, int)} or {@link #makeCandidateListOf(int)} or
     98      * {@code searchWords()}, call this method to get the
     99      * results.  This method will return a candidate in decreasing
    100      * frequency order for {@link #predict(ComposingText, int, int)} and
    101      * {@link #makeCandidateListOf(int)}, in increasing character code order for
    102      * {@code searchWords()}.
    103      *
    104      * @return          The candidate; {@code null} if there is no more candidate.
    105      */
    106     public WnnWord getNextCandidate();
    107 
    108     /**
    109      * Retrieve the list of registered words.
    110      * <br>
    111      * @return          {@code null} if no word is registered; the array of {@link WnnWord} if some words is registered.
    112      */
    113     public WnnWord[] getUserDictionaryWords();
    114 
    115     /**
    116      * Learn a word.
    117      * <br>
    118      * This method is used to register the word selected from
    119      * candidates to the learning dictionary or update the frequency
    120      * of the word.
    121      *
    122      * @param word      The selected word
    123      * @return          {@code true} if success; {@code false} if fail or not supported.
    124      */
    125     public boolean learn(WnnWord word);
    126 
    127     /**
    128      * Register a word to the user's dictionary.
    129      * <br>
    130      * @param word      A word to register
    131      * @return          Number of registered words in the user's dictionary after the operation; minus value if a error occurs.
    132      */
    133     public int addWord(WnnWord word);
    134 
    135     /**
    136      * Delete a word from the user's dictionary.
    137      * <br>
    138      * @param word      A word to delete
    139      * @return          {@code true} if success; {@code false} if fail or not supported.
    140      */
    141     public boolean deleteWord(WnnWord word);
    142 
    143     /**
    144      * Delete all words from the user's dictionary.
    145      * <br>
    146      * @param dictionary    {@code DICTIONARY_TYPE_LEARN} or {@code DICTIONARY_TYPE_USER}
    147      * @return              {@code true} if success; {@code false} if fail or not supported.
    148      */
    149     public boolean initializeDictionary(int dictionary);
    150 
    151     /**
    152      * Delete all words from the user's dictionary of the specified language.
    153      * <br>
    154      * @param dictionary        {@code DICTIONARY_TYPE_LEARN} or {@code DICTIONARY_TYPE_USER}
    155      * @param type              Dictionary type (language, etc...)
    156      * @return                  {@code true} if success; {@code false} if fail or not supported.
    157      */
    158     public boolean initializeDictionary(int dictionary, int type);
    159 
    160     /**
    161      * Reflect the preferences in the converter.
    162      *
    163      * @param pref  The preferences
    164      */
    165     public void setPreferences(SharedPreferences pref);
    166 
    167     /**
    168      * Break the sequence of words.
    169      * <br>
    170      * This method is used to notice breaking the sequence of input
    171      * words to the converter.  The converter will stop learning
    172      * collocation between previous input words and words which will
    173      * input after this break.
    174      */
    175     public void breakSequence();
    176 
    177     /**
    178      * Makes the candidate list.
    179      * <br>
    180      * This method is used when to make a list of other candidates of
    181      * the clause which is in the result of consecutive clause
    182      * conversion({@link #convert(ComposingText)}).
    183      * To get the elements of the list, call {@link #getNextCandidate()}.
    184      *
    185      * @param clausePosition  The position of a clause
    186      * @return                  Plus value if there are candidates; 0 if there is no candidate; minus value if a error occurs.
    187      */
    188     public int makeCandidateListOf(int clausePosition);
    189 }
    190