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_Cb)(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_Cb)(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_Cb)(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 a list of suggested spellings for a misspelled @a word.
84 *
85 * @param tag unique tag to notify the spell checker which document that @a text is associated,
86 * @c 0 can be passed for text not associated with a particular document
87 * @param word the word to get guesses
88 * @return a list of dynamically allocated strings (as char*) and
89 * caller is responsible for destroying them.
90 */
91typedef Eina_List *(*Ewk_Text_Checker_Word_Guesses_Get_Cb)(uint64_t tag, const char *word);
92
93/**
94 * Sets a callback function to add the word to the spell checker dictionary.
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 add
99 */
100typedef void (*Ewk_Text_Checker_Word_Learn_Cb)(uint64_t tag, const char *word);
101
102/**
103 * Sets a callback function to tell the spell checker to ignore a given 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 ignore
108 */
109typedef void (*Ewk_Text_Checker_Word_Ignore_Cb)(uint64_t tag, const char *word);
110
111/**
112 * Sets a callback function to get a unique spell document tag.
113 *
114 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
115 */
116EAPI void ewk_text_checker_unique_spell_document_tag_get_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Get_Cb cb);
117
118/**
119 * Sets a callback function to close a unique spell document tag.
120 *
121 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
122 */
123EAPI void ewk_text_checker_unique_spell_document_tag_close_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Close_Cb cb);
124
125/**
126 * Sets a callback function to search for a misspelled words in the given string.
127 *
128 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
129 */
130EAPI void ewk_text_checker_string_spelling_check_cb_set(Ewk_Text_Checker_String_Spelling_Check_Cb cb);
131
132/**
133 * Sets a callback function to get an array of suggested spellings for a misspelled word.
134 *
135 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
136 */
137EAPI void ewk_text_checker_word_guesses_get_cb_set(Ewk_Text_Checker_Word_Guesses_Get_Cb cb);
138
139/**
140 * Sets a callback function to add the word to the spell checker dictionary.
141 *
142 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
143 */
144EAPI void ewk_text_checker_word_learn_cb_set(Ewk_Text_Checker_Word_Learn_Cb cb);
145
146/**
147 * Sets a callback function to tell the spell checker to ignore a given word.
148 *
149 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
150 */
151EAPI void ewk_text_checker_word_ignore_cb_set(Ewk_Text_Checker_Word_Ignore_Cb cb);
152
153#ifdef __cplusplus
154}
155#endif
156#endif // ewk_text_checker_h