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