Changes between Initial Version and Version 1 of WK2-EFLTextCheckerApiTutorial

Timestamp:

Dec 21, 2012, 2:22:00 AM (13 years ago)

Author:

g.czajkowski@samsung.com

Comment:

--

WK2-EFLTextCheckerApiTutorial

@@ +1 @@
+== Introduction ==
+
+Text Checker feature allows to check spelling in the editable areas for example, input fields, text areas and content editable. Functions:
+ * check spelling of text (while typing to the input element),
+ * get suggestions for the misspelled word (through the context menu),
+ * learn/ignore the misspelled word (through the context menu).
+There is one text checker object per application and it's disabled by default. 
+
+== Enabling text checker feature ==
+
+If application wants to use the feature, API from ewk_settings.h should be used:
+{{{
+ewk_settings_continuous_spell_checking_enabled_set(EINA_TRUE);
+}}}
+
+The client is able to query whether spellchecker continuous spell checking is enabled. Here is an example:
+{{{
+Eina_Bool enabled = ewk_settings_continuous_spell_checking_enabled_get();
+}}}
+    
+== Languages support ==
+By default, WebKit2-EFL performs spell checking based on the default OS language. If the client prefers to use a specific language, he has an opportunity to change it by following API:
+{{{
+const char lang[] = "en_US";
+ewk_settings_spell_checking_languages_set(lang);
+}}}
+
+The client is able to verify the typed text with multi languages support. The languages that are involved in spell checking can be given with comma separated values. Here is an example:
+{{{
+const char langs[] = "en_US,ko,pl";
+ewk_settings_spell_checking_languages_set(langs);
+}}}
+
+The number of the languages is not limited. But please be aware that loading multiple dictionaries may slow down your application.
+There is a possibility to retrieve a list of dictionaries that are supported/installed by OS. Here is an example:
+{{{
+Eina_List *available_langs = ewk_settings_spell_checking_available_languages_get();
+if (!available_langs)
+    return;
+
+Eina_List *it= NULL;
+void *dict = NULL;
+EINA_LIST_FOREACH(available_langs, it, dict)
+    printf("%s\n", (const char*) dict);
+}}}
+
+The client is responsible for destroying the list and its items after use. Here is an example:
+{{{
+EINA_LIST_FREE(available_langs, dict)
+    eina_stringshare_del((const char*) dict);  
+}}}
+
+The client can get a list of dictionaries that have been already loaded and are in use to perform spellchecking. Here is an example:
+{{{
+Eina_List *loaded_langs = ewk_settings_spell_checking_languages_get();
+if (!loaded_langs)
+   return;
+
+Eina_List *it= NULL;
+void *dict = NULL;
+EINA_LIST_FOREACH(loaded_langs, it, dict)
+   printf("%s\n", (const char*) dict);
+}}}
+
+The client is responsible for destroying the list and its items after use. Here is an example:
+{{{
+EINA_LIST_FREE(loaded_langs, dict)
+    eina_stringshare_del((const char*) dict);  
+}}}
+ 
+== Notification about setting change ==
+
+There is a callback function used to notify the client when the continuous spell checking setting was changed by WebKit. Specifying of this callback is needed if the application wants to receive notifications once WebKit changes this setting. If the application is not interested, this callback is not set. Changing of this setting at the WebKit level can be made as a result of modifying options in a Context Menu by a user. Here is an example:
+
+
+{{{
+// Callback definition.
+static void setting_change(Eina_Bool enabled) {                                                                     
+    printf("The continuous spell checking setting has been changed to %d\n", enabled);
+} 
+
+{
+    ...
+    // Callback registration.
+    ewk_settings_continuous_spell_checking_change_cb_set(setting_change);
+}
+}}}
+
+== Overwrite the default text checker implementation by the client ==
+
+The default WebKit text checker implementation is based on the Enchant library (http://www.abisource.com/projects/enchant/). It doesn't ensure grammar checking. Application is able to overwrite it by defining its own implementation and setting appropriate callback functions. To overwrite the default text checker implementation API from ewk_text_checker.h can be used.
+Here is an example of overwriting the implementation of check spelling of the given text:
+{{{
+// Callback definition.
+static void spelling_check(uint64_t tag, const char* text, int32_t* misspelling_location, int32_t* misspelling_length) {
+    printf("WebKit is requesting to check spelling for: %s\", text);
+    // We assume that the text is spelled correctly.
+    *misspelling_location = -1;
+    *misspelling_length = 0;
+}
+
+{
+    ...
+    // Callback registration.
+    ewk_text_checker_string_spelling_check_cb_set(spelling_check);
+}
+}}}
+
+More examples of overwriting the text checker implementation can be found at https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/tests/test_ewk2_text_checker.cpp
+
+==  More detailed information ==
+You can find the unit tests of text checker API here: https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/tests/test_ewk2_text_checker.cpp.
+
+There are more test cases and examples of usage. WebKit-EFL's bots are building and testing text checker API. You can check their results here: http://build.webkit.org/console?category=EFL 
+
+Text checker documentation and its API can be found at:
+ * ewk_text_checker.h (https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_text_checker.h)
+ * ewk_settings.h (https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_settings.h)
+
+== Help, issues ==
+
+For issues with the text checker, please contact:
+ * Grzegorz Czajkowski - g.czajkowski (at) samsung.com
+ * Michal Roj (m.roj (at) samsung.com