NimfIM 3 NIMF Library
NimfIM

## Functions

NimfIM * | nimf_im_new ()
void | nimf_im_focus_in ()
void | nimf_im_focus_out ()
void | nimf_im_reset ()
gboolean | nimf_im_filter_event ()
void | nimf_im_get_preedit_string ()
void | nimf_im_set_cursor_location ()
void | nimf_im_set_use_preedit ()
void | nimf_im_set_surrounding ()

## Signals

void | beep | Run Last
void | commit | Run Last
gboolean | delete-surrounding | Run Last
void | preedit-changed | Run Last
void | preedit-end | Run Last
void | preedit-start | Run Last
gboolean | retrieve-surrounding | Run Last

## Object Hierarchy

        GObject
        ╰── NimfIM

## Description

## Functions

### nimf_im_new ()

    NimfIM *
    nimf_im_new (void);

Creates a new NimfIM.

#### Returns

a new NimfIM

nimf_im_new

### nimf_im_focus_in ()

    void
    nimf_im_focus_in (NimfIM *im);

Notifies the input method that the caller has gained focus.

#### Parameters

im | a NimfIM |

nimf_im_focus_in

### nimf_im_focus_out ()

    void
    nimf_im_focus_out (NimfIM *im);

Notifies the input method that the caller has lost focus.

#### Parameters

im | a NimfIM |

nimf_im_focus_out

### nimf_im_reset ()

    void
    nimf_im_reset (NimfIM *im);

Reset the input method.

#### Parameters

im | a NimfIM |

nimf_im_reset

### nimf_im_filter_event ()

    gboolean
    nimf_im_filter_event (NimfIM *im,
                          NimfEvent *event);

Let the input method handle the event .

#### Parameters

im | a NimfIM |
event | a NimfEvent |

#### Returns

`TRUE` if the input method handled the event .

nimf_im_filter_event

### nimf_im_get_preedit_string ()

    void
    nimf_im_get_preedit_string (NimfIM *im,
                                gchar **str,
                                NimfPreeditAttr ***attrs,
                                gint *cursor_pos);

Retrieve the current preedit string, an array of attributes to apply to the string and position of cursor within the preedit string from the input method.

#### Parameters

im | a NimfIM |
str | location to store the retrieved string. The string retrieved must be freed with `g_free()`. | [out][transfer full]
attrs | location to store the retrieved attribute array. When you are done with this array, you must free it with `nimf_preedit_attr_freev()`. | [out][transfer full]
cursor_pos | location to store position of cursor (in characters) within the preedit string. | [out][transfer full]

nimf_im_get_preedit_string

### nimf_im_set_cursor_location ()

    void
    nimf_im_set_cursor_location (NimfIM *im,
                                 const NimfRectangle *area);

Notifies the input method that a change in cursor position has been made. The location is the position of a window position in root window coordinates.

#### Parameters

im | a NimfIM |
area | new location |

nimf_im_set_cursor_location

### nimf_im_set_use_preedit ()

    void
    nimf_im_set_use_preedit (NimfIM *im,
                             gboolean use_preedit);

If use_preedit is `FALSE` (default is `TRUE`), then the input method may use some other input styles, such as over-the-spot, off-the-spot or root-window.

#### Parameters

im | a NimfIM |
use_preedit | whether the input method should use an on-the-spot input style |

nimf_im_set_use_preedit

### nimf_im_set_surrounding ()

    void
    nimf_im_set_surrounding (NimfIM *im,
                             const char *text,
                             gint len,
                             gint cursor_index);

Sets surrounding text to input method. This function is expected to be called in response to NimfIM::retrieve-surrounding which is emitted by `nimf_engine_emit_retrieve_surrounding()`.

#### Parameters

im | a NimfIM |
text | surrounding text |
len | the byte length of text , or -1 if text is nul-terminated. |
cursor_index | the character index of the cursor within text . |

nimf_im_set_surrounding

## Signal Details

### The `“beep”` signal

    void
    user_function (NimfIM  *im,
                   gpointer user_data)

The “beep” signal is emitted when the input method needs to beep, if supported.

#### Parameters

im | a NimfIM |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

NimfIM::beep

### The `“commit”` signal

    void
    user_function (NimfIM  *im,
                   char    *text,
                   gpointer user_data)

The “commit” signal is emitted when a complete input sequence has been entered by the user.

#### Parameters

im | a NimfIM |
text | text to commit |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

NimfIM::commit

### The `“delete-surrounding”` signal

    gboolean
    user_function (NimfIM  *im,
                   int      offset,
                   int      n_chars,
                   gpointer user_data)

The “delete-surrounding” signal is emitted when the input method needs to delete all or part of the text surrounding the cursor.

#### Parameters

im | a NimfIM |
offset | the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. |
n_chars | the number of characters to be deleted |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the signal was handled.

Flags: Run Last

NimfIM::delete-surrounding

### The `“preedit-changed”` signal

    void
    user_function (NimfIM  *im,
                   gpointer user_data)

The “preedit-changed” signal is emitted whenever the preedit sequence has been changed.

#### Parameters

im | a NimfIM |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

NimfIM::preedit-changed

### The `“preedit-end”` signal

    void
    user_function (NimfIM  *im,
                   gpointer user_data)

The “preedit-end” signal is emitted when a preediting sequence has been completed or canceled.

#### Parameters

im | a NimfIM |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

NimfIM::preedit-end

### The `“preedit-start”` signal

    void
    user_function (NimfIM  *im,
                   gpointer user_data)

The “preedit-start” signal is emitted when a new preediting sequence starts.

#### Parameters

im | a NimfIM |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

NimfIM::preedit-start

### The `“retrieve-surrounding”` signal

    gboolean
    user_function (NimfIM  *im,
                   gpointer user_data)

The “retrieve-surrounding” signal is emitted when the input method requires the text surrounding the cursor. The callback should set the input method surrounding text by calling the `nimf_im_set_surrounding()` method.

#### Parameters

im | a NimfIM |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the signal was handled.

Flags: Run Last

NimfIM::retrieve-surrounding