Changes between Initial Version and Version 1 of WK2-EFLTextCheckerApiTutorial


Ignore:
Timestamp:
Dec 21, 2012 2:22:00 AM (10 years ago)
Author:
g.czajkowski@samsung.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WK2-EFLTextCheckerApiTutorial

    v1 v1  
     1== Introduction ==
     2
     3Text Checker feature allows to check spelling in the editable areas for example, input fields, text areas and content editable. Functions:
     4 * check spelling of text (while typing to the input element),
     5 * get suggestions for the misspelled word (through the context menu),
     6 * learn/ignore the misspelled word (through the context menu).
     7There is one text checker object per application and it's disabled by default.
     8
     9== Enabling text checker feature ==
     10
     11If application wants to use the feature, API from ewk_settings.h should be used:
     12{{{
     13ewk_settings_continuous_spell_checking_enabled_set(EINA_TRUE);
     14}}}
     15
     16The client is able to query whether spellchecker continuous spell checking is enabled. Here is an example:
     17{{{
     18Eina_Bool enabled = ewk_settings_continuous_spell_checking_enabled_get();
     19}}}
     20   
     21== Languages support ==
     22By 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:
     23{{{
     24const char lang[] = "en_US";
     25ewk_settings_spell_checking_languages_set(lang);
     26}}}
     27
     28The 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:
     29{{{
     30const char langs[] = "en_US,ko,pl";
     31ewk_settings_spell_checking_languages_set(langs);
     32}}}
     33
     34The number of the languages is not limited. But please be aware that loading multiple dictionaries may slow down your application.
     35There is a possibility to retrieve a list of dictionaries that are supported/installed by OS. Here is an example:
     36{{{
     37Eina_List *available_langs = ewk_settings_spell_checking_available_languages_get();
     38if (!available_langs)
     39    return;
     40
     41Eina_List *it= NULL;
     42void *dict = NULL;
     43EINA_LIST_FOREACH(available_langs, it, dict)
     44    printf("%s\n", (const char*) dict);
     45}}}
     46
     47The client is responsible for destroying the list and its items after use. Here is an example:
     48{{{
     49EINA_LIST_FREE(available_langs, dict)
     50    eina_stringshare_del((const char*) dict); 
     51}}}
     52
     53The client can get a list of dictionaries that have been already loaded and are in use to perform spellchecking. Here is an example:
     54{{{
     55Eina_List *loaded_langs = ewk_settings_spell_checking_languages_get();
     56if (!loaded_langs)
     57   return;
     58
     59Eina_List *it= NULL;
     60void *dict = NULL;
     61EINA_LIST_FOREACH(loaded_langs, it, dict)
     62   printf("%s\n", (const char*) dict);
     63}}}
     64
     65The client is responsible for destroying the list and its items after use. Here is an example:
     66{{{
     67EINA_LIST_FREE(loaded_langs, dict)
     68    eina_stringshare_del((const char*) dict); 
     69}}}
     70 
     71== Notification about setting change ==
     72
     73There 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:
     74
     75
     76{{{
     77// Callback definition.
     78static void setting_change(Eina_Bool enabled) {                                                                     
     79    printf("The continuous spell checking setting has been changed to %d\n", enabled);
     80}
     81
     82{
     83    ...
     84    // Callback registration.
     85    ewk_settings_continuous_spell_checking_change_cb_set(setting_change);
     86}
     87}}}
     88
     89== Overwrite the default text checker implementation by the client ==
     90
     91The 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.
     92Here is an example of overwriting the implementation of check spelling of the given text:
     93{{{
     94// Callback definition.
     95static void spelling_check(uint64_t tag, const char* text, int32_t* misspelling_location, int32_t* misspelling_length) {
     96    printf("WebKit is requesting to check spelling for: %s\", text);
     97    // We assume that the text is spelled correctly.
     98    *misspelling_location = -1;
     99    *misspelling_length = 0;
     100}
     101
     102{
     103    ...
     104    // Callback registration.
     105    ewk_text_checker_string_spelling_check_cb_set(spelling_check);
     106}
     107}}}
     108
     109More 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
     110
     111==  More detailed information ==
     112You 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.
     113
     114There 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
     115
     116Text checker documentation and its API can be found at:
     117 * ewk_text_checker.h (https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_text_checker.h)
     118 * ewk_settings.h (https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_settings.h)
     119
     120== Help, issues ==
     121
     122For issues with the text checker, please contact:
     123 * Grzegorz Czajkowski - g.czajkowski (at) samsung.com
     124 * Michal Roj (m.roj (at) samsung.com