GNOME.org
 

gtk+ r21870 - in trunk: . docs/reference/gtk docs/reference/gtk/tmpl gtk

Author: daniel
Date: Thu Dec 11 11:38:59 2008
New Revision: 21870
URL: http://svn.gnome.org/viewvc/gtk+?rev=21870&view=rev

Log:
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.


Removed:
   trunk/docs/reference/gtk/tmpl/gtkimcontext.sgml
Modified:
   trunk/ChangeLog
   trunk/docs/reference/gtk/Makefile.am
   trunk/docs/reference/gtk/gtk-sections.txt
   trunk/gtk/gtkimcontext.c
   trunk/gtk/gtkimcontext.h
   trunk/gtk/gtkimmodule.c

Modified: trunk/docs/reference/gtk/Makefile.am
==============================================================================
--- trunk/docs/reference/gtk/Makefile.am	(original)
+++ trunk/docs/reference/gtk/Makefile.am	Thu Dec 11 11:38:59 2008
@@ -45,7 +45,6 @@
 	gtkiconcache.h			\
         gtkiconcachevalidator.h         \
 	gtkiconthemeparser.h		\
-	gtkimmodule.h			\
 	gtkintl.h			\
 	gtkkeyhash.h			\
 	gtkmarshal.h			\

Modified: trunk/docs/reference/gtk/gtk-sections.txt
==============================================================================
--- trunk/docs/reference/gtk/gtk-sections.txt	(original)
+++ trunk/docs/reference/gtk/gtk-sections.txt	Thu Dec 11 11:38:59 2008
@@ -1981,9 +1981,12 @@
 </SECTION>
 
 <SECTION>
+<INCLUDE>gtk/gtkimmodule.h</INCLUDE>
 <FILE>gtkimcontext</FILE>
 <TITLE>GtkIMContext</TITLE>
 GtkIMContext
+GtkIMContextClass
+GtkIMContextInfo
 gtk_im_context_set_client_window
 gtk_im_context_get_preedit_string
 gtk_im_context_filter_keypress

Modified: trunk/gtk/gtkimcontext.c
==============================================================================
--- trunk/gtk/gtkimcontext.c	(original)
+++ trunk/gtk/gtkimcontext.c	Thu Dec 11 11:38:59 2008
@@ -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:
+ *
+ * <informalexample><programlisting>
+ * void im_module_init(#GTypeModule *module);
+ * </programlisting></informalexample>
+ * 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.
+ *
+ * <informalexample><programlisting>
+ * void im_module_exit(void);
+ * </programlisting></informalexample>
+ * Here goes any cleanup code your input method might require on module unload.
+ *
+ * <informalexample><programlisting>
+ * void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts)
+ * {
+ *   *contexts = info_list;
+ *   *n_contexts = G_N_ELEMENTS (info_list);
+ * }
+ * </programlisting></informalexample>
+ * 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.
+ *
+ * <informalexample><programlisting>
+ * #GtkIMContext * im_module_create(const #gchar *context_id);
+ * </programlisting></informalexample>
+ * 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 <filename>gtk.immodules</filename> needs to be
+ * regenerated by <link linkend="gtk-query-immodules-2.0">gtk-query-immodules-2.0</link>,
+ * in order for the new input method to become available to GTK+ applications.
+ */
+
 enum {
   PREEDIT_START,
   PREEDIT_END,
@@ -53,6 +116,63 @@
 
 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 @@
   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 @@
 		  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 @@
 		  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 @@
 		  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_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_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),

Modified: trunk/gtk/gtkimcontext.h
==============================================================================
--- trunk/gtk/gtkimcontext.h	(original)
+++ trunk/gtk/gtkimcontext.h	Thu Dec 11 11:38:59 2008
@@ -49,11 +49,13 @@
 
 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 @@
   gboolean (*get_surrounding)     (GtkIMContext   *context,
 				   gchar         **text,
 				   gint           *cursor_index);
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_gtk_reserved1) (void);
   void (*_gtk_reserved2) (void);

Modified: trunk/gtk/gtkimmodule.c
==============================================================================
--- trunk/gtk/gtkimmodule.c	(original)
+++ trunk/gtk/gtkimmodule.c	Thu Dec 11 11:38:59 2008
@@ -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
+ *   <function>dgettext&lpar;&rpar;</function>.
+ * @domain_dirname: Name of locale directory for use with
+ *   <function>bindtextdomain&lpar;&rpar;</function>.
+ * @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;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]