gtk.IMContext — an abstract base class defining a generic input method interface
class gtk.IMContext(gtk.Object): |
"commit" | def callback( |
def callback( | |
def callback( | |
def callback( | |
def callback( | |
def callback( |
The gtk.IMContext is
an abstract base class used to provide objects to manage the context for
input methods used to support text input in various natural languages. The
character input for some languages (e.g. Chinese, Japanese and Korean)
cannot be easily input using standard keyboards so multiple keystrokes are
used to input a single character. Input methods are used to help this
process by providing feedback of the characters input and managing the
context and valid combinations. Thegtk.IMContext
subclasses manage the required context information for applications and
widgets such as the gtk.Entry and gtk.TextView
widgets.
The gtk.IMContext
manages the context of the text surrounding the cursor and the preedit text
that provides feedback about the in-process multiple character
composition.
def set_client_window(window)
| the client window. This may be
None to indicate that the previous client window no
longer exists. |
The set_client_window() method set the
client window for the input context; this is the gtk.gdk.Window in
which the input appears. This window is used in order to correctly position
status windows, and may also be used for purposes internal to the input
method.
def get_preedit_string()Returns : | a tuple containing the preedit string, the attribute list and the position of cursor (in bytes) within the preedit string. |
The get_preedit_string() method returns
a tuple containing: the current preedit string for the input context, a list
of attributes to apply to the string and the cursor position within the
string. This string should be displayed inserted at the insertion
point.
def filter_keypress(event)
| the key event |
Returns : | True if the input method
handled the keystroke. |
The filter_keypress() method allows an
input method to internally handle a key press event. If this function
returns True, then no further processing should be done
for this keystroke.
def focus_in()The focus_in() method notifies the
input method that the widget to which this input context corresponds has
gained focus. The input method may, for example, change the displayed
feedback to reflect this change.
def focus_out()The focus_out() method notifies the
input method that the widget to which this input context corresponds has
lost focus. The input method may, for example, change the displayed feedback
or reset the context state to reflect this change.
def reset()The reset() method notifies the input
method that a significant change in context (such as a change in cursor
position) has been made. This will typically cause the input method to clear
the preedit state.
def set_cursor_location(area)
| new location |
The set_cursor_location() method
notifies the input method that a change in cursor position has been
made.
def set_use_preedit(use_preedit)
| if True the IM context
should use the preedit string. |
The set_use_preedit() method sets the
use preedit setting to the value of use_preedit. If
use_preedit is True (the default)
the IM context should use the preedit string to display feedback. If
use_preedit is False the IM
context may use some other method to display feedback, such as displaying it
in a child of the root window.
def set_surrounding(text, len, cursor_index)
| the text surrounding the insertion point, as UTF-8. the preedit string should not be included within it. |
| the length of text, or
-1 to calculate the length of
text. |
| the byte index of the insertion cursor within
text. |
The set_surrounding() method sets
surrounding context around the insertion point and preedit string. This
function is expected to be called in response to the "retrieve_surrounding"
signal, and will likely have no effect if called at other times.
def get_surrounding()Returns : | a tuple containing the UTF-8 encoded string of text holding context around the insertion point and the byte index of the insertion cursor within the string, or None if no surrounding context was retrieved. |
The get_surrounding() method returns a
tuple containing the text surrounding the cursor and the byte index of the
cursor within the text. 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.
This function is implemented by emitting the
"retrieve_surrounding" signal on the input method; in response to this
signal, a widget should provide as much context as is available, up to an
entire paragraph, by calling set_surrounding().
Note that there is no obligation for a widget to respond to the
"retrieve_surrounding" signal, so input methods must be prepared to function
without context.
def delete_surrounding(offset, n_chars)
| the offset from cursor position in chars; a negative value means start before the cursor. |
| the number of characters to delete. |
Returns : | True if the signal was
handled. |
The delete_surrounding() method asks the widget that the input
context is attached to to delete characters around the cursor position by
emitting the "delete_surrounding" signal. Note that
offset and n_chars are in
characters not in bytes, which differs from the usage other places in the
gtk.IMContext
class.
In order to use this function, you should first call get_surrounding()
to get the current context, and call this function immediately afterward to
make sure that you know what you are deleting. You should also account for
the fact that even if the signal was handled, the input context might not
have deleted all the characters that were requested to be deleted.
This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications.
def callback(imcontext, string, user_param1, ...)
| the imcontext that received the signal |
| the text to be committed |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "commit" signal is emitted when the text is ready to be displayed.
def callback(imcontext, user_param1, ...)
| the imcontext that received the signal |
| the offset from the cursor position of the text to be deleted |
| the number of characters to be deleted |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
Returns : | True if the signal was
handled. |
The "delete-surrounding" signal is emitted when the input method needs to delete the context text.
def callback(imcontext, user_param1, ...)
| the imcontext that received the signal |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "preedit-changed" signal is emitted when the preedit text has changed.
def callback(imcontext, user_param1, ...)
| the imcontext that received the signal |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "preedit-end" signal is emitted when preediting is completed.
def callback(imcontext, user_param1, ...)
| the imcontext that received the signal |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "preedit-start" signal is emitted when preediting is started.
def callback(imcontext, user_param1, ...)
| the imcontext that received the signal |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
Returns : | True if the signal was
handled. |
The "retrieve-surrounding" signal is emitted when the input
method requires the context surrounding the cursor. The callback should set
the input method surrounding context by calling the set_surrounding()
method. The method returns True if the signal was handled
by the callback.