1/* 2 * Copyright (C) 2012-2013 Samsung Electronics 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 13 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 14 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 15 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 22 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 23 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 */ 25 26/** 27 * @file ewk_text_checker.h 28 * @brief Provides API to overwrite the default WebKit spellchecker implementation 29 * and contains API to manipulate spellchecker settings. 30 * 31 * There is one spellchecker object per application. 32 * It allows to check spelling in the editable areas, get suggestions for the misspelled word, 33 * learn and ignore spelling. 34 * 35 * If application wants to check spelling while typing, ewk_text_checker_continuous_spell_checking_enabled_set API 36 * should be used. 37 * 38 * The default WebKit spellchecker implementation is based on the Enchant library. 39 * It doesn't ensure grammar checking. Application is able to overwrite the default 40 * WebKit spellchecker implementation by defining its own implementation and setting 41 * appropriate callback functions. 42 */ 43 44#ifndef ewk_text_checker_h 45#define ewk_text_checker_h 46 47#include <Evas.h> 48 49#ifdef __cplusplus 50extern "C" { 51#endif 52 53/** 54 * Creates a type name for the callback function used to notify the client when 55 * the continuous spell checking setting was changed by WebKit. 56 * 57 * @param enable @c EINA_TRUE if continuous spell checking is enabled or @c EINA_FALSE if it's disabled 58 */ 59typedef void (*Ewk_Text_Checker_Continuous_Spell_Checking_Change_Cb)(Eina_Bool enable); 60 61/** 62 * Defines a type name for the callback function to return a tag (identifier) which is guaranteed to be unique. 63 * 64 * Unique tags help to avoid collisions with other objects that are checked for spelling mistakes. 65 * 66 * @param o the view object to get unique tag 67 * 68 * @return unique tag for the given @a o view object 69 */ 70typedef uint64_t (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Get_Cb)(const Evas_Object *o); 71 72/** 73 * Defines a type name for the callback function to close the prviously set tag. 74 * 75 * This callback will notify the receiver that the user has finished with the tagged document. 76 * 77 * @param tag the tag to be closed 78 */ 79typedef void (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Close_Cb)(uint64_t tag); 80 81/** 82 * Defines a type name for the callback function to search for a misspelled words in the given string. 83 * 84 * @param tag unique tag to notify the spell checker which document that @a text is associated, 85 * in most cases not necessarily, just for ignored word, 86 * @c 0 can be passed in for text not associated with a particular document 87 * @param text the text containing the words to spellcheck 88 * @param misspelling_location a pointer to store the beginning of the misspelled @a text, @c -1 if the @a text is correct 89 * @param misspelling_length a pointer to store the length of misspelled @a text, @c 0 if the @a text is correct 90 */ 91typedef void (*Ewk_Text_Checker_String_Spelling_Check_Cb)(uint64_t tag, const char *text, int32_t *misspelling_location, int32_t *misspelling_length); 92 93/** 94 * Defines a type name for the callback function to get a list of suggested spellings for a misspelled @a word. 95 * 96 * @param tag unique tag to notify the spell checker which document that @a text is associated, 97 * @c 0 can be passed for text not associated with a particular document 98 * @param word the word to get guesses 99 * @return a list of dynamically allocated strings (as char*), 100 * the list and its items will be freed by WebKit. 101 */ 102typedef Eina_List *(*Ewk_Text_Checker_Word_Guesses_Get_Cb)(uint64_t tag, const char *word); 103 104/** 105 * Sets a callback function to add the word to the spell checker dictionary. 106 * 107 * @param tag unique tag to notify the spell checker which document that @a text is associated, 108 * @c 0 can be passed for text not associated with a particular document 109 * @param word the word to add 110 */ 111typedef void (*Ewk_Text_Checker_Word_Learn_Cb)(uint64_t tag, const char *word); 112 113/** 114 * Sets a callback function to tell the spell checker to ignore a given word. 115 * 116 * @param tag unique tag to notify the spell checker which document that @a text is associated, 117 * @c 0 can be passed for text not associated with a particular document 118 * @param word the word to ignore 119 */ 120typedef void (*Ewk_Text_Checker_Word_Ignore_Cb)(uint64_t tag, const char *word); 121 122 123/** 124 * Queries if continuous spell checking is enabled. 125 * 126 * @return @c EINA_TRUE if continuous spell checking is enabled or @c EINA_FALSE if it's disabled 127 */ 128EAPI Eina_Bool ewk_text_checker_continuous_spell_checking_enabled_get(void); 129 130/** 131 * Enables/disables continuous spell checking. 132 * 133 * This feature is disabled by default. 134 * 135 * @see ewk_text_checker_continuous_spell_checking_change_cb_set 136 * 137 * @param enable @c EINA_TRUE to enable continuous spell checking or @c EINA_FALSE to disable 138 */ 139EAPI void ewk_text_checker_continuous_spell_checking_enabled_set(Eina_Bool enable); 140 141/** 142 * Gets the the list of all available the spell checking languages to use. 143 * 144 * @see ewk_settings_spell_checking_languages_set 145 * 146 * @return the list with available spell checking languages, or @c NULL on failure 147 * the Eina_List and its items should be freed after, use eina_stringshare_del() 148 */ 149EAPI Eina_List *ewk_text_checker_spell_checking_available_languages_get(void); 150 151/** 152 * Sets @a languages as the list of languages to use by default WebKit 153 * implementation of spellchecker feature with Enchant library support. 154 * 155 * If @languages is @c NULL, the default language is used. 156 * If the default language can not be determined then any available dictionary will be used. 157 * 158 * @note This function invalidates the previously set languages. 159 * The dictionaries are requested asynchronously. 160 * 161 * @param languages a list of comma (',') separated language codes 162 * of the form 'en_US', ie, language_VARIANT, may be @c NULL. 163 */ 164EAPI void ewk_text_checker_spell_checking_languages_set(const char *languages); 165 166/** 167 * Gets the the list of the spell checking languages in use. 168 * 169 * @see ewk_settings_spell_checking_available_languages_get 170 * @see ewk_settings_spell_checking_languages_set 171 * 172 * @return the list with the spell checking languages in use, 173 * the Eina_List and its items should be freed after, use eina_stringshare_del() 174 */ 175EAPI Eina_List *ewk_text_checker_spell_checking_languages_get(void); 176 177/** 178 * Sets a callback function used to notify the client when 179 * the continuous spell checking setting was changed by WebKit. 180 * 181 * Specifying of this callback is needed if the application wants to receive notifications 182 * once WebKit changes this setting. 183 * If the application is not interested, this callback is not set. 184 * Changing of this setting at the WebKit level can be made as a result of modifying 185 * options in a Context Menu by a user. 186 * 187 * @param cb a new callback function to set or @c NULL to invalidate the previous one 188 */ 189EAPI void ewk_text_checker_continuous_spell_checking_change_cb_set(Ewk_Text_Checker_Continuous_Spell_Checking_Change_Cb cb); 190 191/** 192 * Sets a callback function to get a unique spell document tag. 193 * 194 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 195 */ 196EAPI void ewk_text_checker_unique_spell_document_tag_get_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Get_Cb cb); 197 198/** 199 * Sets a callback function to close a unique spell document tag. 200 * 201 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 202 */ 203EAPI void ewk_text_checker_unique_spell_document_tag_close_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Close_Cb cb); 204 205/** 206 * Sets a callback function to search for a misspelled words in the given string. 207 * 208 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 209 */ 210EAPI void ewk_text_checker_string_spelling_check_cb_set(Ewk_Text_Checker_String_Spelling_Check_Cb cb); 211 212/** 213 * Sets a callback function to get an array of suggested spellings for a misspelled word. 214 * 215 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 216 */ 217EAPI void ewk_text_checker_word_guesses_get_cb_set(Ewk_Text_Checker_Word_Guesses_Get_Cb cb); 218 219/** 220 * Sets a callback function to add the word to the spell checker dictionary. 221 * 222 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 223 */ 224EAPI void ewk_text_checker_word_learn_cb_set(Ewk_Text_Checker_Word_Learn_Cb cb); 225 226/** 227 * Sets a callback function to tell the spell checker to ignore a given word. 228 * 229 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation 230 */ 231EAPI void ewk_text_checker_word_ignore_cb_set(Ewk_Text_Checker_Word_Ignore_Cb cb); 232 233#ifdef __cplusplus 234} 235#endif 236#endif // ewk_text_checker_h 237