1/*
2 * Copyright (C) 2012 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 *
30 * There is one spellchecker object per application and it's disabled by default.
31 * It allows to check spelling in the editable areas.
32 * If application wants to enable the feature, API from @a ewk_text_checker_setting.h
33 * should be used.
34 *
35 * The default WebKit spellchecker implementation is based on the Enchant library.
36 * It doesn't ensure grammar checking. Application is able to overwrite the default
37 * WebKit spellchecker implementation by defining its own implementation and setting
38 * appropriate callback functions.
39 */
40
41#ifndef ewk_text_checker_h
42#define ewk_text_checker_h
43
44#include <Evas.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/**
51 * Defines a type name for the callback function to return a tag (identifier) which is guaranteed to be unique.
52 *
53 * Unique tags help to avoid collisions with other objects that are checked for spelling mistakes.
54 *
55 * @param o the view object to get unique tag
56 *
57 * @return unique tag for the given @a o view object
58 */
59typedef uint64_t (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Get)(const Evas_Object *o);
60
61/**
62 * Defines a type name for the callback function to close the prviously set tag.
63 *
64 * This callback will notify the receiver that the user has finished with the tagged document.
65 *
66 * @param tag the tag to be closed
67 */
68typedef void (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Close)(uint64_t tag);
69
70/**
71 * Defines a type name for the callback function to search for a misspelled words in the given string.
72 *
73 * @param tag unique tag to notify the spell checker which document that @a text is associated,
74 * in most cases not necessarily, just for ignored word,
75 * @c 0 can be passed in for text not associated with a particular document
76 * @param text the text containing the words to spellcheck
77 * @param misspelling_location a pointer to store the beginning of the misspelled @a text, @c -1 if the @a text is correct
78 * @param misspelling_length a pointer to store the length of misspelled @a text, @c 0 if the @a text is correct
79 */
80typedef void (*Ewk_Text_Checker_String_Spelling_Check)(uint64_t tag, const char *text, int32_t *misspelling_location, int32_t *misspelling_length);
81
82/**
83 * Defines a type name for the callback function to get the status of UI Spelling.
84 *
85 * @return @c EINA_TRUE if the UI Spelling is shown, @c EINA_FALSE if it's hidden
86 */
87typedef Eina_Bool (*Ewk_Text_Checker_UI_Spelling_Status_Get)(void);
88
89/**
90 * Defines a type name for the callback function to toggle the UI Spelling.
91 */
92typedef void (*Ewk_Text_Checker_UI_Spelling_Status_Toggle)(void);
93
94/**
95 * Defines a type name for the callback function to update the UI Spelling for the misspelled word.
96 *
97 * @param tag unique tag to notify the spell checker which document that the misspelled word is associated,
98 * @param misspelled_word the misspelled word
99 */
100typedef void (*Ewk_Text_Checker_UI_Spelling_Misspelled_Word_Update)(uint64_t tag, const char *misspelled_word);
101
102/**
103 * Defines a type name for the callback function to get a list of suggested spellings for a misspelled @a word.
104 *
105 * @param tag unique tag to notify the spell checker which document that @a text is associated,
106 * @c 0 can be passed for text not associated with a particular document
107 * @param word the word to get guesses
108 * @return a list of dynamically allocated strings (as char*) and
109 * caller is responsible for destroying them.
110 */
111typedef Eina_List *(*Ewk_Text_Checker_Word_Guesses_Get)(uint64_t tag, const char *word);
112
113/**
114 * Sets a callback function to add the word to the spell checker dictionary.
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 add
119 */
120typedef void (*Ewk_Text_Checker_Word_Learn)(uint64_t tag, const char *word);
121
122/**
123 * Sets a callback function to tell the spell checker to ignore a given word.
124 *
125 * @param tag unique tag to notify the spell checker which document that @a text is associated,
126 * @c 0 can be passed for text not associated with a particular document
127 * @param word the word to ignore
128 */
129typedef void (*Ewk_Text_Checker_Word_Ignore)(uint64_t tag, const char *word);
130
131/**
132 * Sets a callback function to get a unique spell document tag.
133 *
134 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
135 */
136EAPI void ewk_text_checker_unique_spell_document_tag_get_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Get cb);
137
138/**
139 * Sets a callback function to close a unique spell document tag.
140 *
141 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
142 */
143EAPI void ewk_text_checker_unique_spell_document_tag_close_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Close cb);
144
145/**
146 * Sets a callback function to search for a misspelled words in the given string.
147 *
148 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
149 */
150EAPI void ewk_text_checker_string_spelling_check_cb_set(Ewk_Text_Checker_String_Spelling_Check cb);
151
152/**
153 * Sets a callback function to get the status of UI Spelling.
154 *
155 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
156 */
157EAPI void ewk_text_checker_ui_spelling_status_get_cb_set(Ewk_Text_Checker_UI_Spelling_Status_Get cb);
158
159/**
160 * Sets a callback function to toggle the UI Spelling.
161 *
162 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
163 */
164EAPI void ewk_text_checker_ui_spelling_status_toggle_cb_set(Ewk_Text_Checker_UI_Spelling_Status_Toggle cb);
165
166/**
167 * Sets a callback function to update the UI Spelling for the misspelled word.
168 *
169 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
170 */
171EAPI void ewk_text_checker_ui_spelling_misspelled_word_update_cb_set(Ewk_Text_Checker_UI_Spelling_Misspelled_Word_Update cb);
172
173/**
174 * Sets a callback function to get an array of suggested spellings for a misspelled word.
175 *
176 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
177 */
178EAPI void ewk_text_checker_word_guesses_get_cb_set(Ewk_Text_Checker_Word_Guesses_Get cb);
179
180/**
181 * Sets a callback function to add the word to the spell checker dictionary.
182 *
183 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
184 */
185EAPI void ewk_text_checker_word_learn_cb_set(Ewk_Text_Checker_Word_Learn cb);
186
187/**
188 * Sets a callback function to tell the spell checker to ignore a given word.
189 *
190 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
191 */
192EAPI void ewk_text_checker_word_ignore_cb_set(Ewk_Text_Checker_Word_Ignore cb);
193
194#ifdef __cplusplus
195}
196#endif
197#endif // ewk_text_checker_h