AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-27 14:10:30 +00:00
Code Issues Projects Releases Wiki Activity

imcontext: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-03-01 01:48:09 -05:00 committed by Emmanuele Bassi
parent 3eeaef0834
commit e2cab4d406
1 changed files with 137 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

289
gtk/gtkimcontext.c
View File

@ -24,77 +24,45 @@
#include "gtkintl.h" #include "gtkintl.h"
/** /**
* SECTION:gtkimcontext * GtkIMContext:
* @title: GtkIMContext
* @short_description: Base class for input method contexts
* @include: gtk/gtk.h,gtk/gtkimmodule.h
* *
* #GtkIMContext defines the interface for GTK input methods. An input method * `GtkIMContext` defines the interface for GTK input methods.
* is used by GTK text input widgets like #GtkEntry to map from key events to
* Unicode character strings.
* *
* The default input method can be set programmatically via the * `GtkIMContext` is used by GTK text input widgets like `GtkText`
* #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set * to map from key events to Unicode character strings.
* the GTK_IM_MODULE environment variable as documented in
* [Running GTK Applications][gtk-running].
* *
* The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module * By default, GTK uses a platform-dependent default input method.
* properties may also be used to set input methods for specific widget * On Windows, the default implementation is IME-based and on Wayland,
* instances. For instance, a certain entry widget might be expected to contain * it is using the Wayland text protocol. The choice can be overridden
* certain characters which would be easier to input with a certain input * programmatically via the [property@Gtk.Settings:gtk-im-module] setting.
* method. * Users may set the `GTK_IM_MODULE` environment variable to override the
* default.
* *
* An input method may consume multiple key events in sequence and finally * Text widgets have a :im-module property (e.g. [property@Gtk.TextView:im-module])
* output the composed result. This is called preediting, and an input method * that may also be used to set input methods for specific widget instances.
* may provide feedback about this process by displaying the intermediate * For instance, a certain entry widget might be expected to contain
* composition states as preedit text. For instance, the default GTK input * certain characters which would be easier to input with a specific
* method implements the input of arbitrary Unicode code points by holding down * input method.
* the Control and Shift keys and then typing “U” followed by the hexadecimal *
* digits of the code point. When releasing the Control and Shift keys, * An input method may consume multiple key events in sequence before finally
* preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for * outputting the composed result. This is called *preediting*, and an input
* example results in the € sign. * method may provide feedback about this process by displaying the intermediate
* composition states as preedit text.
*
* For instance, the built-in GTK input method `GtkIMContextSimple` implements
* the input of arbitrary Unicode code points by holding down the
* <kbd>Control</kbd> and <kbd>Shift</kbd> keys and then typing <kbd>U</kbd>
* followed by the hexadecimal digits of the code point. When releasing the
* <kbd>Control</kbd> and <kbd>Shift</kbd> keys, preediting ends and the
* character is inserted as text. For example,
*
* Ctrl+Shift+u 2 0 A C
*
* results in the € sign.
* *
* Additional input methods can be made available for use by GTK widgets as * Additional input methods can be made available for use by GTK widgets as
* loadable modules. An input method module is a small shared library which * loadable modules. An input method module is a small shared library which
* implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports * provides a `GIOExtension` for the extension point named "gtk-im-module".
* these four functions:
*
* |[<!-- language="C" -->
* void im_module_init(GTypeModule *module);
* ]|
* This function should register the #GType of the #GtkIMContext subclass which
* implements the input method by means of g_type_module_register_type(). Note
* that g_type_register_static() cannot be used as the type needs to be
* registered dynamically.
*
* |[<!-- language="C" -->
* void im_module_exit(void);
* ]|
* Here goes any cleanup code your input method might require on module unload.
*
* |[<!-- language="C" -->
* void im_module_list(const GtkIMContextInfo ***contexts, int *n_contexts)
* {
* *contexts = info_list;
* *n_contexts = G_N_ELEMENTS (info_list);
* }
* ]|
* This function returns the list of input methods provided by the module. The
* example implementation above shows a common solution and simply returns a
* pointer to statically defined array of #GtkIMContextInfo items for each
* provided input method.
*
* |[<!-- language="C" -->
* GtkIMContext * im_module_create(const char *context_id);
* ]|
* This function should return a pointer to a newly created instance of the
* #GtkIMContext subclass identified by @context_id. The context ID is the same
* as specified in the #GtkIMContextInfo array returned by im_module_list().
*
* After a new loadable input method module has been installed on the system,
* the configuration file `gtk.immodules` needs to be
* regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0],
* in order for the new input method to become available to GTK applications.
*/ */
enum { enum {
@ -467,15 +435,16 @@ gtk_im_context_real_get_surrounding_with_selection (GtkIMContext *context,
/** /**
* gtk_im_context_set_client_widget: * gtk_im_context_set_client_widget:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @widget: (allow-none): the client widget. This may be %NULL to indicate * @widget: (allow-none): the client widget. This may be %NULL to indicate
* that the previous client widget no longer exists. * that the previous client widget no longer exists.
* *
* Set the client window for the input context; this is the * Set the client widget for the input context.
* #GtkWidget holding the input focus. This widget is *
* This is the `GtkWidget` holding the input focus. This widget is
* used in order to correctly position status windows, and may * used in order to correctly position status windows, and may
* also be used for purposes internal to the input method. * also be used for purposes internal to the input method.
**/ */
void void
gtk_im_context_set_client_widget (GtkIMContext *context, gtk_im_context_set_client_widget (GtkIMContext *context,
GtkWidget *widget) GtkWidget *widget)
@ -491,20 +460,20 @@ gtk_im_context_set_client_widget (GtkIMContext *context,
/** /**
* gtk_im_context_get_preedit_string: * gtk_im_context_get_preedit_string:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @str: (out) (transfer full): location to store the retrieved * @str: (out) (transfer full): location to store the retrieved
* string. The string retrieved must be freed with g_free(). * string. The string retrieved must be freed with g_free().
* @attrs: (out) (transfer full): location to store the retrieved * @attrs: (out) (transfer full): location to store the retrieved
* attribute list. When you are done with this list, you * attribute list. When you are done with this list, you
* must unreference it with pango_attr_list_unref(). * must unreference it with pango_attr_list_unref().
* @cursor_pos: (out): location to store position of cursor (in characters) * @cursor_pos: (out): location to store position of cursor (in characters)
* within the preedit string. * within the preedit string.
* *
* Retrieve the current preedit string for the input context, * Retrieve the current preedit string for the input context,
* and a list of attributes to apply to the string. * and a list of attributes to apply to the string.
* This string should be displayed inserted at the insertion *
* point. * This string should be displayed inserted at the insertion point.
**/ */
void void
gtk_im_context_get_preedit_string (GtkIMContext *context, gtk_im_context_get_preedit_string (GtkIMContext *context,
char **str, char **str,
@ -522,16 +491,17 @@ gtk_im_context_get_preedit_string (GtkIMContext *context,
/** /**
* gtk_im_context_filter_keypress: * gtk_im_context_filter_keypress:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @event: the key event * @event: the key event
*
* Allow an input method to internally handle key press and release
* events. If this function returns %TRUE, then no further processing
* should be done for this key event.
*
* Returns: %TRUE if the input method handled the key event.
* *
**/ * Allow an input method to internally handle key press and release
* events.
*
* If this function returns %TRUE, then no further processing
* should be done for this key event.
*
* Returns: %TRUE if the input method handled the key event.
*/
gboolean gboolean
gtk_im_context_filter_keypress (GtkIMContext *context, gtk_im_context_filter_keypress (GtkIMContext *context,
GdkEvent *key) GdkEvent *key)
@ -547,7 +517,7 @@ gtk_im_context_filter_keypress (GtkIMContext *context,
/** /**
* gtk_im_context_filter_key: * gtk_im_context_filter_key:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @press: whether to forward a key press or release event * @press: whether to forward a key press or release event
* @surface: the surface the event is for * @surface: the surface the event is for
* @device: the device that the event is for * @device: the device that the event is for
@ -557,7 +527,7 @@ gtk_im_context_filter_keypress (GtkIMContext *context,
* @group: the active keyboard group for the event * @group: the active keyboard group for the event
* *
* Allow an input method to forward key press and release events * Allow an input method to forward key press and release events
* to another input method, without necessarily having a GdkEvent * to another input methodm without necessarily having a `GdkEvent`
* available. * available.
* *
* Returns: %TRUE if the input method handled the key event. * Returns: %TRUE if the input method handled the key event.
@ -631,13 +601,14 @@ gtk_im_context_filter_key (GtkIMContext *context,
/** /**
* gtk_im_context_focus_in: * gtk_im_context_focus_in:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* *
* Notify the input method that the widget to which this * Notify the input method that the widget to which this
* input context corresponds has gained focus. The input method * input context corresponds has gained focus.
* may, for example, change the displayed feedback to reflect *
* this change. * The input method may, for example, change the displayed
**/ * feedback to reflect this change.
*/
void void
gtk_im_context_focus_in (GtkIMContext *context) gtk_im_context_focus_in (GtkIMContext *context)
{ {
@ -652,13 +623,14 @@ gtk_im_context_focus_in (GtkIMContext *context)
/** /**
* gtk_im_context_focus_out: * gtk_im_context_focus_out:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* *
* Notify the input method that the widget to which this * Notify the input method that the widget to which this
* input context corresponds has lost focus. The input method * input context corresponds has lost focus.
* may, for example, change the displayed feedback or reset the contexts *
* state to reflect this change. * The input method may, for example, change the displayed
**/ * feedback or reset the contexts state to reflect this change.
*/
void void
gtk_im_context_focus_out (GtkIMContext *context) gtk_im_context_focus_out (GtkIMContext *context)
{ {
@ -673,12 +645,13 @@ gtk_im_context_focus_out (GtkIMContext *context)
/** /**
* gtk_im_context_reset: * gtk_im_context_reset:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* *
* Notify the input method that a change such as a change in cursor * Notify the input method that a change such as a change in cursor
* position has been made. This will typically cause the input * position has been made.
* method to clear the preedit state. *
**/ * This will typically cause the input method to clear the preedit state.
*/
void void
gtk_im_context_reset (GtkIMContext *context) gtk_im_context_reset (GtkIMContext *context)
{ {
@ -694,13 +667,14 @@ gtk_im_context_reset (GtkIMContext *context)
/** /**
* gtk_im_context_set_cursor_location: * gtk_im_context_set_cursor_location:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @area: new location * @area: new location
* *
* Notify the input method that a change in cursor * Notify the input method that a change in cursor
* position has been made. The location is relative to the client * position has been made.
* window. *
**/ * The location is relative to the client window.
*/
void void
gtk_im_context_set_cursor_location (GtkIMContext *context, gtk_im_context_set_cursor_location (GtkIMContext *context,
const GdkRectangle *area) const GdkRectangle *area)
@ -716,14 +690,16 @@ gtk_im_context_set_cursor_location (GtkIMContext *context,
/** /**
* gtk_im_context_set_use_preedit: * gtk_im_context_set_use_preedit:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @use_preedit: whether the IM context should use the preedit string. * @use_preedit: whether the IM context should use the preedit string.
* *
* Sets whether the IM context should use the preedit string * Sets whether the IM context should use the preedit string
* to display feedback. If @use_preedit is FALSE (default * to display feedback.
* is TRUE), then the IM context may use some other method to display *
* feedback, such as displaying it in a child of the root window. * If @use_preedit is %FALSE (default is %TRUE), then the IM context
**/ * may use some other method to display feedback, such as displaying
* it in a child of the root window.
*/
void void
gtk_im_context_set_use_preedit (GtkIMContext *context, gtk_im_context_set_use_preedit (GtkIMContext *context,
gboolean use_preedit) gboolean use_preedit)
@ -739,7 +715,7 @@ gtk_im_context_set_use_preedit (GtkIMContext *context,
/** /**
* gtk_im_context_set_surrounding: * gtk_im_context_set_surrounding:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @text: text surrounding the insertion point, as UTF-8. * @text: text surrounding the insertion point, as UTF-8.
* the preedit string should not be included within * the preedit string should not be included within
* @text. * @text.
@ -747,11 +723,13 @@ gtk_im_context_set_use_preedit (GtkIMContext *context,
* @cursor_index: the byte index of the insertion cursor within @text. * @cursor_index: the byte index of the insertion cursor within @text.
* *
* Sets surrounding context around the insertion point and preedit * Sets surrounding context around the insertion point and preedit
* string. This function is expected to be called in response to the * string.
* GtkIMContext::retrieve_surrounding signal, and will likely have no
* effect if called at other times.
* *
* Deprecated: 4.2: Use gtk_im_context_set_surrounding_with_selection() instead * This function is expected to be called in response to the
* [signal@Gtk.IMContext::retrieve-surrounding] signal, and will
* likely have no effect if called at other times.
*
* Deprecated: 4.2: Use [method@Gtk.IMContext.set_surrounding_with_selection] instead
*/ */
void void
gtk_im_context_set_surrounding (GtkIMContext *context, gtk_im_context_set_surrounding (GtkIMContext *context,
@ -805,31 +783,34 @@ gtk_im_context_set_surrounding_with_selection (GtkIMContext *context,
/** /**
* gtk_im_context_get_surrounding: * gtk_im_context_get_surrounding:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @text: (out) (transfer full): location to store a UTF-8 encoded * @text: (out) (transfer full): location to store a UTF-8 encoded
* string of text holding context around the insertion point. * string of text holding context around the insertion point.
* If the function returns %TRUE, then you must free the result * If the function returns %TRUE, then you must free the result
* stored in this location with g_free(). * stored in this location with g_free().
* @cursor_index: (out): location to store byte index of the insertion * @cursor_index: (out): location to store byte index of the insertion
* cursor within @text. * cursor within @text.
* *
* Retrieves context around the insertion point. Input methods * Retrieves context around the insertion point.
* typically want context in order to constrain input text based on *
* existing text; this is important for languages such as Thai where * Input methods typically want context in order to constrain input text
* only some sequences of characters are allowed. * 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 * This function is implemented by emitting the
* GtkIMContext::retrieve_surrounding signal on the input method; in * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
* response to this signal, a widget should provide as much context as * in response to this signal, a widget should provide as much context as
* is available, up to an entire paragraph, by calling * is available, up to an entire paragraph, by calling
* gtk_im_context_set_surrounding(). Note that there is no obligation * [method@Gtk.IMContext.set_surrounding].
* for a widget to respond to the ::retrieve_surrounding signal, so input
* methods must be prepared to function without context.
* *
* Returns: %TRUE if surrounding text was provided; in this case * Note that there is no obligation for a widget to respond to the
* you must free the result stored in *text. * `::retrieve-surrounding` signal, so input methods must be prepared to
* function without context.
* *
* Deprecated: 4.2: Use gtk_im_context_get_surrounding_with_selection() instead. * Returns: `TRUE` if surrounding text was provided; in this case
* you must free the result stored in `text`.
*
* Deprecated: 4.2: Use [method@Gtk.IMContext.get_surrounding_with_selection] instead.
*/ */
gboolean gboolean
gtk_im_context_get_surrounding (GtkIMContext *context, gtk_im_context_get_surrounding (GtkIMContext *context,
@ -846,29 +827,32 @@ gtk_im_context_get_surrounding (GtkIMContext *context,
* gtk_im_context_get_surrounding_with_selection: * gtk_im_context_get_surrounding_with_selection:
* @context: a #GtkIMContext * @context: a #GtkIMContext
* @text: (out) (transfer full): location to store a UTF-8 encoded * @text: (out) (transfer full): location to store a UTF-8 encoded
* string of text holding context around the insertion point. * string of text holding context around the insertion point.
* If the function returns %TRUE, then you must free the result * If the function returns %TRUE, then you must free the result
* stored in this location with g_free(). * stored in this location with g_free().
* @cursor_index: (out): location to store byte index of the insertion * @cursor_index: (out): location to store byte index of the insertion
* cursor within @text. * cursor within @text.
* @anchor_index: (out): location to store byte index of the selection * @anchor_index: (out): location to store byte index of the selection
* bound within @text * bound within @text
* *
* Retrieves context around the insertion point. Input methods * Retrieves context around the insertion point.
* typically want context in order to constrain input text based on *
* existing text; this is important for languages such as Thai where * Input methods typically want context in order to constrain input
* only some sequences of characters are allowed. * 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 * This function is implemented by emitting the
* GtkIMContext::retrieve_surrounding signal on the input method; in * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
* response to this signal, a widget should provide as much context as * in response to this signal, a widget should provide as much context as
* is available, up to an entire paragraph, by calling * is available, up to an entire paragraph, by calling
* gtk_im_context_set_surrounding(). Note that there is no obligation * [method@Gtk.IMContext.set_surrounding_with_selection].
* for a widget to respond to the ::retrieve_surrounding signal, so input
* methods must be prepared to function without context.
* *
* Returns: %TRUE if surrounding text was provided; in this case * Note that there is no obligation for a widget to respond to the
* you must free the result stored in *text. * `::retrieve-surrounding` signal, so input methods must be prepared to
* function without context.
*
* Returns: `TRUE` if surrounding text was provided; in this case
* you must free the result stored in `text`.
*/ */
gboolean gboolean
gtk_im_context_get_surrounding_with_selection (GtkIMContext *context, gtk_im_context_get_surrounding_with_selection (GtkIMContext *context,
@ -909,16 +893,17 @@ gtk_im_context_get_surrounding_with_selection (GtkIMContext *context,
/** /**
* gtk_im_context_delete_surrounding: * gtk_im_context_delete_surrounding:
* @context: a #GtkIMContext * @context: a `GtkIMContext`
* @offset: offset from cursor position in chars; * @offset: offset from cursor position in chars;
* a negative value means start before the cursor. * a negative value means start before the cursor.
* @n_chars: number of characters to delete. * @n_chars: number of characters to delete.
* *
* Asks the widget that the input context is attached to delete * Asks the widget that the input context is attached to delete
* characters around the cursor position by emitting the * characters around the cursor position by emitting the
* GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars * GtkIMContext::delete_surrounding signal.
* are in characters not in bytes which differs from the usage other *
* places in #GtkIMContext. * Note that @offset and @n_chars are in characters not in bytes
* which differs from the usage other places in #GtkIMContext.
* *
* In order to use this function, you should first call * In order to use this function, you should first call
* gtk_im_context_get_surrounding() to get the current context, and * gtk_im_context_get_surrounding() to get the current context, and