/*
 * Copyright (C) 2012 Samsung Electronics
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * @file ewk_text_checker.h
 * @brief Provides API to overwrite the default WebKit spellchecker implementation.
 *
 * There is one spellchecker object per application and it's disabled by default.
 * It allows to check spelling in the editable areas.
 * If application wants to enable the feature, API from ewk_settings.h
 * should be used.
 *
 * The default WebKit spellchecker implementation is based on the Enchant library.
 * It doesn't ensure grammar checking. Application is able to overwrite the default
 * WebKit spellchecker implementation by defining its own implementation and setting
 * appropriate callback functions.
 */

#ifndef ewk_text_checker_h
#define ewk_text_checker_h

#include <Evas.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Defines a type name for the callback function to return a tag (identifier) which is guaranteed to be unique.
 *
 * Unique tags help to avoid collisions with other objects that are checked for spelling mistakes.
 *
 * @param o the view object to get unique tag
 *
 * @return unique tag for the given @a o view object
 */
typedef uint64_t (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Get_Cb)(const Evas_Object *o);

/**
 * Defines a type name for the callback function to close the prviously set tag.
 *
 * This callback will notify the receiver that the user has finished with the tagged document.
 *
 * @param tag the tag to be closed
 */
typedef void (*Ewk_Text_Checker_Unique_Spell_Document_Tag_Close_Cb)(uint64_t tag);

/**
 * Defines a type name for the callback function to search for a misspelled words in the given string.
 *
 * @param tag unique tag to notify the spell checker which document that @a text is associated,
 *        in most cases not necessarily, just for ignored word,
 *        @c 0 can be passed in for text not associated with a particular document
 * @param text the text containing the words to spellcheck
 * @param misspelling_location a pointer to store the beginning of the misspelled @a text, @c -1 if the @a text is correct
 * @param misspelling_length a pointer to store the length of misspelled @a text, @c 0 if the @a text is correct
 */
typedef void (*Ewk_Text_Checker_String_Spelling_Check_Cb)(uint64_t tag, const char *text, int32_t *misspelling_location, int32_t *misspelling_length);

/**
 * Defines a type name for the callback function to get a list of suggested spellings for a misspelled @a word.
 *
 * @param tag unique tag to notify the spell checker which document that @a text is associated,
 *        @c 0 can be passed for text not associated with a particular document
 * @param word the word to get guesses
 * @return a list of dynamically allocated strings (as char*) and
 *         caller is responsible for destroying them.
 */
typedef Eina_List *(*Ewk_Text_Checker_Word_Guesses_Get_Cb)(uint64_t tag, const char *word);

/**
 * Sets a callback function to add the word to the spell checker dictionary.
 *
 * @param tag unique tag to notify the spell checker which document that @a text is associated,
 *        @c 0 can be passed for text not associated with a particular document
 * @param word the word to add
 */
typedef void (*Ewk_Text_Checker_Word_Learn_Cb)(uint64_t tag, const char *word);

/**
 * Sets a callback function to tell the spell checker to ignore a given word.
 *
 * @param tag unique tag to notify the spell checker which document that @a text is associated,
 *        @c 0 can be passed for text not associated with a particular document
 * @param word the word to ignore
 */
typedef void (*Ewk_Text_Checker_Word_Ignore_Cb)(uint64_t tag, const char *word);

/**
 * Sets a callback function to get a unique spell document tag.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_unique_spell_document_tag_get_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Get_Cb cb);

/**
 * Sets a callback function to close a unique spell document tag.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_unique_spell_document_tag_close_cb_set(Ewk_Text_Checker_Unique_Spell_Document_Tag_Close_Cb cb);

/**
 * Sets a callback function to search for a misspelled words in the given string.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_string_spelling_check_cb_set(Ewk_Text_Checker_String_Spelling_Check_Cb cb);

/**
 * Sets a callback function to get an array of suggested spellings for a misspelled word.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_word_guesses_get_cb_set(Ewk_Text_Checker_Word_Guesses_Get_Cb cb);

/**
 * Sets a callback function to add the word to the spell checker dictionary.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_word_learn_cb_set(Ewk_Text_Checker_Word_Learn_Cb cb);

/**
 * Sets a callback function to tell the spell checker to ignore a given word.
 *
 * @param cb a new callback to set or @c NULL to restore the default WebKit callback implementation
 */
EAPI void ewk_text_checker_word_ignore_cb_set(Ewk_Text_Checker_Word_Ignore_Cb cb);

#ifdef __cplusplus
}
#endif
#endif // ewk_text_checker_h