From 0bf3652e1df37321d4c2318f5bbf67438010f987 Mon Sep 17 00:00:00 2001 From: Daniel Elstner Date: Thu, 11 Dec 2008 11:38:59 +0000 Subject: [PATCH] =?UTF-8?q?Bug=20563994=20=E2=80=93=20Input=20method=20mod?= =?UTF-8?q?ule=20interface=20not=20documented?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gtk/gtkimcontext.h: Add public/private markers. * gtk/gtkimcontext.c: Add section documentation which explains how to add a new input method module to GTK+. Document the signals and virtual functions of GtkIMContextClass. * gtk/gtkimmodule.c: Document struct GtkIMContextInfo. * docs/reference/gtk/gtk-sections.txt: Add GtkIMContextClass and GtkIMContextInfo to section GtkIMContext. * docs/reference/gtk/Makefile.am (IGNORE_HFILES): Remove gtkimmodule.h from the list in order to pick up GtkIMContextInfo. * docs/reference/gtk/tmpl/gtkimcontext.sgml: Remove file from repository since all the hand-edited content has been migrated to source file comments. svn path=/trunk/; revision=21870 --- ChangeLog | 17 ++ docs/reference/gtk/Makefile.am | 1 - docs/reference/gtk/gtk-sections.txt | 3 + docs/reference/gtk/tmpl/gtkimcontext.sgml | 177 --------------------- gtk/gtkimcontext.c | 180 +++++++++++++++++++++- gtk/gtkimcontext.h | 4 +- gtk/gtkimmodule.c | 14 ++ 7 files changed, 213 insertions(+), 183 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkimcontext.sgml diff --git a/ChangeLog b/ChangeLog index 568a49cdfc..37a0233a9b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2008-12-11 Daniel Elstner + + Bug 563994 – Input method module interface not documented + + * gtk/gtkimcontext.h: Add public/private markers. + * gtk/gtkimcontext.c: Add section documentation which explains how + to add a new input method module to GTK+. Document the signals and + virtual functions of GtkIMContextClass. + * gtk/gtkimmodule.c: Document struct GtkIMContextInfo. + * docs/reference/gtk/gtk-sections.txt: Add GtkIMContextClass and + GtkIMContextInfo to section GtkIMContext. + * docs/reference/gtk/Makefile.am (IGNORE_HFILES): Remove + gtkimmodule.h from the list in order to pick up GtkIMContextInfo. + * docs/reference/gtk/tmpl/gtkimcontext.sgml: Remove file from + repository since all the hand-edited content has been migrated to + source file comments. + 2008-12-10 Matthias Clasen Bug 563991 – gtk_file_chooser_button_new_with_backend is deprecated diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index af527eecb9..3c33134b58 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -45,7 +45,6 @@ IGNORE_HFILES= \ gtkiconcache.h \ gtkiconcachevalidator.h \ gtkiconthemeparser.h \ - gtkimmodule.h \ gtkintl.h \ gtkkeyhash.h \ gtkmarshal.h \ diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index e3a69d9b97..1ec1925d09 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -1981,9 +1981,12 @@ gtk_image_menu_item_get_type
+gtk/gtkimmodule.h gtkimcontext GtkIMContext GtkIMContext +GtkIMContextClass +GtkIMContextInfo gtk_im_context_set_client_window gtk_im_context_get_preedit_string gtk_im_context_filter_keypress diff --git a/docs/reference/gtk/tmpl/gtkimcontext.sgml b/docs/reference/gtk/tmpl/gtkimcontext.sgml deleted file mode 100644 index 1a4e946f29..0000000000 --- a/docs/reference/gtk/tmpl/gtkimcontext.sgml +++ /dev/null @@ -1,177 +0,0 @@ - -GtkIMContext - - -Base class for input method contexts - - - - - - - - - - - - - - - - - - - - - - - - - -@imcontext: the object which received the signal. -@arg1: - - - - - - -@imcontext: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@imcontext: the object which received the signal. - - - - - - -@imcontext: the object which received the signal. - - - - - - -@imcontext: the object which received the signal. - - - - - - -@imcontext: the object which received the signal. -@Returns: - - - - - - -@context: -@window: - - - - - - - -@context: -@str: -@attrs: -@cursor_pos: - - - - - - - -@context: -@event: -@Returns: - - - - - - - -@context: - - - - - - - -@context: - - - - - - - -@context: - - - - - - - -@context: -@area: - - - - - - - -@context: -@use_preedit: - - - - - - - -@context: -@text: -@len: -@cursor_index: - - - - - - - -@context: -@text: -@cursor_index: -@Returns: - - - - - - - -@context: -@offset: -@n_chars: -@Returns: - - diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c index 519e223ac5..3887d4a58e 100644 --- a/gtk/gtkimcontext.c +++ b/gtk/gtkimcontext.c @@ -25,6 +25,69 @@ #include "gtkintl.h" #include "gtkalias.h" +/** + * SECTION: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 + * is used by GTK+ text input widgets like #GtkEntry to map from key events to + * Unicode character strings. + * + * An input method may consume multiple key events in sequence and finally + * output the composed result. This is called preediting, and an input method + * may provide feedback about this process by displaying the intermediate + * composition states as preedit text. For instance, the default GTK+ input + * method implements the input of arbitrary Unicode code points by holding down + * 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, + * preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for + * example results in the € sign. + * + * 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 + * implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports + * these four functions: + * + * + * 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. + * + * + * void im_module_exit(void); + * + * Here goes any cleanup code your input method might require on module unload. + * + * + * 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. + * + * + * #GtkIMContext * im_module_create(const #gchar *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-2.0, + * in order for the new input method to become available to GTK+ applications. + */ + enum { PREEDIT_START, PREEDIT_END, @@ -53,6 +116,63 @@ static void gtk_im_context_real_set_surrounding (GtkIMContext *context, G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT) +/** + * GtkIMContextClass: + * @preedit_start: Default handler of the #GtkIMContext::preedit-start signal. + * @preedit_end: Default handler of the #GtkIMContext::preedit-end signal. + * @preedit_changed: Default handler of the #GtkIMContext::preedit-changed + * signal. + * @commit: Default handler of the #GtkIMContext::commit signal. + * @retrieve_surrounding: Default handler of the + * #GtkIMContext::retrieve-surrounding signal. + * @delete_surrounding: Default handler of the + * #GtkIMContext::delete-surrounding signal. + * @set_client_window: Called via gtk_im_context_set_client_window() when the + * input window where the entered text will appear changes. Override this to + * keep track of the current input window, for instance for the purpose of + * positioning a status display of your input method. + * @get_preedit_string: Called via gtk_im_context_get_preedit_string() to + * retrieve the text currently being preedited for display at the cursor + * position. Any input method which composes complex characters or any + * other compositions from multiple sequential key presses should override + * this method to provide feedback. + * @filter_keypress: Called via gtk_im_context_filter_keypress() on every + * key press or release event. Every non-trivial input method needs to + * override this in order to implement the mapping from key events to text. + * A return value of %TRUE indicates to the caller that the event was + * consumed by the input method. In that case, the #GtkIMContext::commit + * signal should be emitted upon completion of a key sequence to pass the + * resulting text back to the input widget. Alternatively, %FALSE may be + * returned to indicate that the event wasn't handled by the input method. + * If a builtin mapping exists for the key, it is used to produce a + * character. + * @focus_in: Called via gtk_im_context_focus_in() when the input widget + * has gained focus. May be overridden to keep track of the current focus. + * @focus_out: Called via gtk_im_context_focus_in() when the input widget + * has lost focus. May be overridden to keep track of the current focus. + * @reset: Called via gtk_im_context_reset() to signal a change such as a + * change in cursor position. An input method that implements preediting + * should override this method to clear the preedit state on reset. + * @set_cursor_location: Called via gtk_im_context_set_cursor_location() + * to inform the input method of the current cursor location relative to + * the client window. May be overridden to implement the display of popup + * windows at the cursor position. + * @set_use_preedit: Called via gtk_im_context_set_use_preedit() to control + * the use of the preedit string. Override this to display feedback by some + * other means if turned off. + * @set_surrounding: Called via gtk_im_context_set_surrounding() in response + * to signal #GtkIMContext::retrieve-surrounding to update the input + * method's idea of the context around the cursor. It is not necessary to + * override this method even with input methods which implement + * context-dependent behavior. The base implementation is sufficient for + * gtk_im_context_get_surrounding() to work. + * @get_surrounding: Called via gtk_im_context_get_surrounding() to update + * the context around the cursor location. It is not necessary to override + * this method even with input methods which implement context-dependent + * behavior. The base implementation emits + * #GtkIMContext::retrieve-surrounding and records the context received + * by the subsequent invocation of @get_surrounding. + */ static void gtk_im_context_class_init (GtkIMContextClass *klass) { @@ -61,6 +181,13 @@ gtk_im_context_class_init (GtkIMContextClass *klass) klass->get_surrounding = gtk_im_context_real_get_surrounding; klass->set_surrounding = gtk_im_context_real_set_surrounding; + /** + * GtkIMContext::preedit-start: + * @context: the object on which the signal is emitted + * + * The ::preedit-start signal is emitted when a new preediting sequence + * starts. + */ im_context_signals[PREEDIT_START] = g_signal_new (I_("preedit-start"), G_TYPE_FROM_CLASS (klass), @@ -69,7 +196,13 @@ gtk_im_context_class_init (GtkIMContextClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * GtkIMContext::preedit-end: + * @context: the object on which the signal is emitted + * + * The ::preedit-end signal is emitted when a preediting sequence + * has been completed or canceled. + */ im_context_signals[PREEDIT_END] = g_signal_new (I_("preedit-end"), G_TYPE_FROM_CLASS (klass), @@ -78,7 +211,15 @@ gtk_im_context_class_init (GtkIMContextClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * GtkIMContext::preedit-changed: + * @context: the object on which the signal is emitted + * + * The ::preedit-changed signal is emitted whenever the preedit sequence + * currently being entered has changed. It is also emitted at the end of + * a preedit sequence, in which case + * gtk_im_context_get_preedit_string() returns the empty string. + */ im_context_signals[PREEDIT_CHANGED] = g_signal_new (I_("preedit-changed"), G_TYPE_FROM_CLASS (klass), @@ -87,7 +228,15 @@ gtk_im_context_class_init (GtkIMContextClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * GtkIMContext::commit: + * @context: the object on which the signal is emitted + * @str: the completed character(s) entered by the user + * + * The ::commit signal is emitted when a complete input sequence + * has been entered by the user. This can be a single character + * immediately after a key press or the final result of preediting. + */ im_context_signals[COMMIT] = g_signal_new (I_("commit"), G_TYPE_FROM_CLASS (klass), @@ -97,7 +246,17 @@ gtk_im_context_class_init (GtkIMContextClass *klass) _gtk_marshal_VOID__STRING, G_TYPE_NONE, 1, G_TYPE_STRING); - + /** + * GtkIMContext::retrieve-surrounding: + * @context: the object on which the signal is emitted + * + * 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 + * gtk_im_context_set_surrounding() method. + * + * Return value: %TRUE if the signal was handled. + */ im_context_signals[RETRIEVE_SURROUNDING] = g_signal_new (I_("retrieve-surrounding"), G_TYPE_FROM_CLASS (klass), @@ -106,6 +265,19 @@ gtk_im_context_class_init (GtkIMContextClass *klass) _gtk_boolean_handled_accumulator, NULL, _gtk_marshal_BOOLEAN__VOID, G_TYPE_BOOLEAN, 0); + /** + * GtkIMContext::delete-surrounding: + * @context: the object on which the signal is emitted + * @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 + * + * The ::delete-surrounding signal is emitted when the input method + * needs to delete all or part of the context surrounding the cursor. + * + * Return value: %TRUE if the signal was handled. + */ im_context_signals[DELETE_SURROUNDING] = g_signal_new (I_("delete-surrounding"), G_TYPE_FROM_CLASS (klass), diff --git a/gtk/gtkimcontext.h b/gtk/gtkimcontext.h index 7e92f76ceb..a0f26471a5 100644 --- a/gtk/gtkimcontext.h +++ b/gtk/gtkimcontext.h @@ -49,11 +49,13 @@ struct _GtkIMContext struct _GtkIMContextClass { + /*< private >*/ /* Yes, this should be GObjectClass, be we can't fix it without breaking * binary compatibility - see bug #90935 */ GtkObjectClass parent_class; + /*< public >*/ /* Signals */ void (*preedit_start) (GtkIMContext *context); void (*preedit_end) (GtkIMContext *context); @@ -87,7 +89,7 @@ struct _GtkIMContextClass gboolean (*get_surrounding) (GtkIMContext *context, gchar **text, gint *cursor_index); - + /*< private >*/ /* Padding for future expansion */ void (*_gtk_reserved1) (void); void (*_gtk_reserved2) (void); diff --git a/gtk/gtkimmodule.c b/gtk/gtkimmodule.c index 8a2fdeed56..125f685e63 100644 --- a/gtk/gtkimmodule.c +++ b/gtk/gtkimmodule.c @@ -51,6 +51,20 @@ #define SIMPLE_ID "gtk-im-context-simple" +/** + * GtkIMContextInfo: + * @context_id: The unique identification string of the input method. + * @context_name: The human-readable name of the input method. + * @domain: Translation domain to be used with + * dgettext(). + * @domain_dirname: Name of locale directory for use with + * bindtextdomain(). + * @default_locales: A colon-separated list of locales where this input method + * should be the default. The asterisk "*" sets the default for all locales. + * + * Bookkeeping information about a loadable input method. + */ + typedef struct _GtkIMModule GtkIMModule; typedef struct _GtkIMModuleClass GtkIMModuleClass;