Ecore Input Method Context Module Functions
Ecore » Ecore_IMF - Ecore Input Method Library Functions

Functions that should be used by Ecore Input Method Context modules. More...

## Functions

EAPI Ecore_IMF_Context * | ecore_imf_context_new (const Ecore_IMF_Context_Class *ctxc)
| Creates a new Input Method Context with klass specified by `ctxc`.
EAPI void | ecore_imf_context_data_set (Ecore_IMF_Context *ctx, void *data)
| Sets the Input Method Context specific data.
EAPI void * | ecore_imf_context_data_get (Ecore_IMF_Context *ctx)
| Gets the Input Method Context specific data.
EAPI Eina_Bool | ecore_imf_context_surrounding_get (Ecore_IMF_Context *ctx, char **text, int *cursor_pos)
| Retrieves context around insertion point.
EAPI Eina_Bool | ecore_imf_context_selection_get (Ecore_IMF_Context *ctx, char **text)
| Retrieves the selected text.
EINA_DEPRECATED EAPI void | ecore_imf_context_preedit_start_event_add (Ecore_IMF_Context *ctx)
| Adds ECORE_IMF_EVENT_PREEDIT_START to the event queue.
EINA_DEPRECATED EAPI void | ecore_imf_context_preedit_end_event_add (Ecore_IMF_Context *ctx)
| Adds ECORE_IMF_EVENT_PREEDIT_END to the event queue.
EINA_DEPRECATED EAPI void | ecore_imf_context_preedit_changed_event_add (Ecore_IMF_Context *ctx)
| Adds ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue.
EINA_DEPRECATED EAPI void | ecore_imf_context_commit_event_add (Ecore_IMF_Context *ctx, const char *str)
| Adds ECORE_IMF_EVENT_COMMIT to the event queue.
EINA_DEPRECATED EAPI void | ecore_imf_context_delete_surrounding_event_add (Ecore_IMF_Context *ctx, int offset, int n_chars)
| Adds ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.
EAPI void | ecore_imf_context_event_callback_call (Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, void *event_info)
| Calls a given callback on the context `ctx`.

## Detailed Description

Functions that should be used by Ecore Input Method Context modules.

## Function Documentation

## ecore_imf_context_new()

EAPI Ecore_IMF_Context * ecore_imf_context_new | ( | const Ecore_IMF_Context_Class * | ctxc | ) |

Creates a new Input Method Context with klass specified by `ctxc`.

This method should be used by modules implementing the Input Method Context interface.

Parameters

  ctxc | An Ecore_IMF_Context_Class.

Returns
  A new Ecore_IMF_Context; on failure it returns NULL.

## ecore_imf_context_data_set()

EAPI void ecore_imf_context_data_set | ( | Ecore_IMF_Context * | ctx,
|  | void * | data )

Sets the Input Method Context specific data.

Note that this method should be used by modules to set the Input Method Context specific data and it's not meant to be used by applications to store application specific data.

Parameters

  ctx | An Ecore_IMF_Context.
  data | The Input Method Context specific data.

Returns
  A new Ecore_IMF_Context; on failure it returns NULL.

## ecore_imf_context_data_get()

EAPI void * ecore_imf_context_data_get | ( | Ecore_IMF_Context * | ctx | ) |

Gets the Input Method Context specific data.

See ecore_imf_context_data_set for more details.

Parameters

  ctx | An Ecore_IMF_Context.

Returns
  The Input Method Context specific data.

## ecore_imf_context_surrounding_get()

EAPI Eina_Bool ecore_imf_context_surrounding_get | ( | Ecore_IMF_Context * | ctx,
|  | char ** | text,
|  | int * | cursor_pos )

Retrieves context around insertion point.

Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. In addition, the text around the insertion point can be used for supporting autocapital feature.

This function is implemented by calling the Ecore_IMF_Context::retrieve_surrounding_func ( set using ecore_imf_context_retrieve_surrounding_callback_set).

There is no obligation for a widget to respond to the retrieve_surrounding_func, so input methods must be prepared to function without context.

Parameters

  ctx | An Ecore_IMF_Context.
  text | Location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns `EINA_TRUE`, then you must free the result stored in this location with free().
  cursor_pos | Location to store the position in characters of the insertion cursor within `text`.

Returns
  `EINA_TRUE` if surrounding text was provided; otherwise `EINA_FALSE`.

References EINA_FALSE.

## ecore_imf_context_selection_get()

EAPI Eina_Bool ecore_imf_context_selection_get | ( | Ecore_IMF_Context * | ctx,
|  | char ** | text )

Retrieves the selected text.

This function is implemented by calling the Ecore_IMF_Context::retrieve_selection_func ( set using ecore_imf_context_retrieve_selection_callback_set).

There is no obligation for a widget to respond to the retrieve_surrounding_func, so input methods must be prepared to function without context.

Parameters

  ctx | An Ecore_IMF_Context.
  text | Location to store a UTF-8 encoded string of the selected text. If the function returns `EINA_TRUE`, then you must free the result stored in this location with free().

Returns
  `EINA_TRUE` if selected text was provided; otherwise `EINA_FALSE`.

Since
  1.9.0

References EINA_FALSE.

## ecore_imf_context_preedit_start_event_add()

EINA_DEPRECATED EAPI void ecore_imf_context_preedit_start_event_add | ( | Ecore_IMF_Context * | ctx | ) |

Adds ECORE_IMF_EVENT_PREEDIT_START to the event queue.

ECORE_IMF_EVENT_PREEDIT_START should be added when a new preedit sequence starts. It's asynchronous method to put event to the event queue. ecore_imf_context_event_callback_call() can be used as synchronous method.

Parameters

  ctx | An Ecore_IMF_Context.

Deprecated
  use ecore_imf_context_event_callback_call() instead.

References ecore_event_add(), and EINA_SAFETY_ON_NULL_RETURN.

## ecore_imf_context_preedit_end_event_add()

EINA_DEPRECATED EAPI void ecore_imf_context_preedit_end_event_add | ( | Ecore_IMF_Context * | ctx | ) |

Adds ECORE_IMF_EVENT_PREEDIT_END to the event queue.

ECORE_IMF_EVENT_PREEDIT_END should be added when a new preedit sequence has been completed or canceled. It's asynchronous method to put event to the event queue. ecore_imf_context_event_callback_call() can be used as synchronous method.

Parameters

  ctx | An Ecore_IMF_Context.

Deprecated
  use ecore_imf_context_event_callback_call() instead.

References ecore_event_add(), and EINA_SAFETY_ON_NULL_RETURN.

## ecore_imf_context_preedit_changed_event_add()

EINA_DEPRECATED EAPI void ecore_imf_context_preedit_changed_event_add | ( | Ecore_IMF_Context * | ctx | ) |

Adds ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue.

It's asynchronous method to put event to the event queue. ecore_imf_context_event_callback_call() can be used as synchronous method.

Parameters

  ctx | An Ecore_IMF_Context.

Deprecated
  use ecore_imf_context_event_callback_call() instead.

References ecore_event_add(), and EINA_SAFETY_ON_NULL_RETURN.

## ecore_imf_context_commit_event_add()

EINA_DEPRECATED EAPI void ecore_imf_context_commit_event_add | ( | Ecore_IMF_Context * | ctx,
|  | const char * | str )

Adds ECORE_IMF_EVENT_COMMIT to the event queue.

It's asynchronous method to put event to the event queue. ecore_imf_context_event_callback_call() can be used as synchronous method.

Parameters

  ctx | An Ecore_IMF_Context.
  str | The committed string.

Deprecated
  use ecore_imf_context_event_callback_call() instead.

References ecore_event_add(), and EINA_SAFETY_ON_NULL_RETURN.

## ecore_imf_context_delete_surrounding_event_add()

EINA_DEPRECATED EAPI void ecore_imf_context_delete_surrounding_event_add | ( | Ecore_IMF_Context * | ctx,
|  | int | offset,
|  | int | n_chars )

Adds ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.

Asks the widget that the input context is attached to to delete characters around the cursor position by adding the ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue. Note that offset and n_chars are in characters not in bytes.

It's asynchronous method to put ECORE_IMF_EVENT_DELETE_SURROUNDING event to the event queue. ecore_imf_context_event_callback_call() can be used as synchronous method.

Parameters

  ctx | An Ecore_IMF_Context.
  offset | The start offset of surrounding to be deleted.
  n_chars | The number of characters to be deleted.

Deprecated
  use ecore_imf_context_event_callback_call() instead.

References ecore_event_add().

## ecore_imf_context_event_callback_call()

EAPI void ecore_imf_context_event_callback_call | ( | Ecore_IMF_Context * | ctx,
|  | Ecore_IMF_Callback_Type | type,
|  | void * | event_info )

Calls a given callback on the context `ctx`.

ecore_imf_context_preedit_start_event_add(), ecore_imf_context_preedit_end_event_add(), ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_commit_event_add() and ecore_imf_context_delete_surrounding_event_add() APIs are asynchronous because those API adds each event to the event queue.

This API provides the way to call each callback function immediately.

Parameters

  ctx | Ecore_IMF_Context.
  type | The type of event that will trigger the callback
  event_info | The pointer to event specific struct or information to pass to the callback functions registered on this event

Since
  1.2.0

References EINA_LIST_FOREACH.