== Abstract ==
The tutorial shows the text checker API and its usage, it describes:
* functions provided by the text checker feature,
* how to enable the feature,
* how to set languages to be used in spell checking,
* how to to be notified on the text checker settings change,
* how to override the default text checker implementation.

== Introduction ==

Text Checker feature allows to check spelling in the editable areas (such ad input fields, text areas and content editable). Functions provided by the text checker feature are as follows:
 * check if spelling of text is correct (while typing the input text),
 * get suggestions for the misspelled word (this is made through feature available in the context menu),
 * learn/ignore the misspelled word (through the feature available in context menu).
The feature is available for [http://trac.webkit.org/wiki/EFLWebKit EFL's WebKit2 port]. There is one text checker object per application and it's disabled by default. The text checker feature is language-neutral. However, relevant dictionaries should be set to perform spelling.

== Enabling text checker feature ==

If an application wants to use this feature, the following API from ewk_settings.h should be used:
{{{
void ewk_settings_continuous_spell_checking_enabled_set(Eina_Bool enable);
}}}
Here is an example how an application can enable this feature:
{{{
ewk_settings_continuous_spell_checking_enabled_set(EINA_TRUE);
}}}
As a result, the text checker feature is enabled and the spell checking related functionalities are available for the user.



The user is able to query whether spellchecker continuous spell checking is enabled, the following API from ewk_settings.h should be used:
{{{
Eina_Bool ewk_settings_continuous_spell_checking_enabled_get(void);
}}}
Here is an example of its usage:
{{{
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. An arbitrary language can be set by using the following API from the ewk_settings.h:
{{{
void ewk_settings_spell_checking_languages_set(const char *languages);
}}}

The example below sets English languages (US version) that will be used to perform spell checking.
{{{
const char lang[] = "en_US";
ewk_settings_spell_checking_languages_set(lang);
}}}

The user is able to verify the typed text with multi languages support. The languages to be used in spell checking can be given as comma separated strings. Here is an example:
{{{
const char langs[] = "en_US,ko,pl";
ewk_settings_spell_checking_languages_set(langs);
}}}
The presented example sets three languages (English, Korean and Polish) to be used in spell checking. The number of the languages is not limited. However, be aware that loading multiple dictionaries may slow down your application.[[BR]]

There is a possibility to retrieve a list of dictionaries that are supported/installed by OS. The following API from ewk_settings.h should be used:
{{{
Eina_List *ewk_settings_spell_checking_available_languages_get(void);
}}}

Here is an example of its usage. It gets the available languages and displays them on the standard output:
{{{
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 presented example gets the languages that are in use and displays them on the standard output. 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 user 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. The following API from ewk_settings.h can be used:
{{{
void ewk_settings_continuous_spell_checking_change_cb_set(Ewk_Settings_Continuous_Spell_Checking_Change_Cb cb);
typedef void (*Ewk_Settings_Continuous_Spell_Checking_Change_Cb)(Eina_Bool enable);
}}}

The presented example registers the callback and displays a message with a new value of the continuous spell checking:
{{{
// 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);
}
}}}

== Overdrive the default text checker implementation by the client ==

The default WebKit text checker implementation is based on the [http://www.abisource.com/projects/enchant/ Enchant] library. It doesn't ensure grammar checking. The application is able to override it by defining its own implementation and setting appropriate callback functions. To override the default text checker implementation API from ewk_text_checker.h can be used:
{{{
void ewk_text_checker_string_spelling_check_cb_set(Ewk_Text_Checker_String_Spelling_Check_Cb cb);
typedef void (*Ewk_Text_Checker_String_Spelling_Check_Cb)(uint64_t tag, const char *text, int32_t *misspelling_location, int32_t *misspelling_length);
}}}

Here is an example of overriding 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 [https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/tests/test_ewk2_text_checker.cpp here].

==  More detailed information ==
You can find the unit tests of text checker API [https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/tests/test_ewk2_text_checker.cpp here]. There are more test cases and examples of the API usage. WebKit-EFL's bots are building and testing text checker API. You can check their results [http://build.webkit.org/console?category=EFL here].

The text checker documentation and its API can be found at:
 * [https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_settings.h ewk_settings.h],
 * [https://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/efl/ewk_text_checker.h ewk_text_checker.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