mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-05 16:20:10 +00:00
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. svn path=/trunk/; revision=21870
This commit is contained in:
parent
8a11a01ae9
commit
0bf3652e1d
17
ChangeLog
17
ChangeLog
@ -1,3 +1,20 @@
|
||||
2008-12-11 Daniel Elstner <danielk@openismus.com>
|
||||
|
||||
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 <mclasen@redhat.com>
|
||||
|
||||
Bug 563991 – gtk_file_chooser_button_new_with_backend is deprecated
|
||||
|
@ -45,7 +45,6 @@ IGNORE_HFILES= \
|
||||
gtkiconcache.h \
|
||||
gtkiconcachevalidator.h \
|
||||
gtkiconthemeparser.h \
|
||||
gtkimmodule.h \
|
||||
gtkintl.h \
|
||||
gtkkeyhash.h \
|
||||
gtkmarshal.h \
|
||||
|
@ -1981,9 +1981,12 @@ gtk_image_menu_item_get_type
|
||||
</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
|
||||
|
@ -1,177 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
GtkIMContext
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
Base class for input method contexts
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GtkIMContext ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::commit ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
@arg1:
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::delete-surrounding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
@arg1:
|
||||
@arg2:
|
||||
@Returns:
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::preedit-changed ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::preedit-end ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::preedit-start ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
|
||||
<!-- ##### SIGNAL GtkIMContext::retrieve-surrounding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@imcontext: the object which received the signal.
|
||||
@Returns:
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_set_client_window ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@window:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_get_preedit_string ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@str:
|
||||
@attrs:
|
||||
@cursor_pos:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_filter_keypress ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@event:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_focus_in ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_focus_out ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_reset ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_set_cursor_location ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@area:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_set_use_preedit ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@use_preedit:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_set_surrounding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@text:
|
||||
@len:
|
||||
@cursor_index:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_get_surrounding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@text:
|
||||
@cursor_index:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_im_context_delete_surrounding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@context:
|
||||
@offset:
|
||||
@n_chars:
|
||||
@Returns:
|
||||
|
||||
|
@ -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 @@ 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),
|
||||
|
@ -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);
|
||||
|
@ -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()</function>.
|
||||
* @domain_dirname: Name of locale directory for use with
|
||||
* <function>bindtextdomain()</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;
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user