Add: - A ::retrieve_surrounding signal that asks the widget for context

Thu Nov  1 16:20:56 2001  Owen Taylor  <otaylor@redhat.com>

	* gtk/gtkimcontext.[ch]: Add:
	  - A ::retrieve_surrounding signal that asks the widget for
	    context around the insertion point.
	  - A ::delete_surrounding signal that asks the widget to
	    delete context aroudn the insertion point.
	  - gtk_im_context_set_context() for widgets to set context
	    around the insertion point in response to ::retrieve_context.
	  - gtk_im_context_get_context() for context to get context
	    around the insertion point

	* gtkmarshal.list: Add BOOL:INT,INT

	* gtk/gtkimmulticontext.c: Proxy the get_surrounding() /
	set_surrounding() methods, and the ::retrieve_surrounding /
	::delete_surrounding signals.

	* gtk/gtkentry.c gtk/gtktreeview.c: Hook up to the
	GtkIMContext::retrieve_surrounding / ::delete_surrounding
	signals.

1 files changed, 229 insertions, 6 deletions

diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 46057a6ff2..1e441682af 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -18,13 +18,17 @@
  */
 
 #include "gtkimcontext.h"
+#include "gtkmain.h"		/* For _gtk_boolean_handled_accumulator */
 #include "gtksignal.h"
+#include "string.h"
 
 enum {
   PREEDIT_START,
   PREEDIT_END,
   PREEDIT_CHANGED,
   COMMIT,
+  RETRIEVE_SURROUNDING,
+  DELETE_SURROUNDING,
   LAST_SIGNAL
 };
 
@@ -33,12 +37,19 @@ static guint im_context_signals[LAST_SIGNAL] = { 0 };
 static void gtk_im_context_class_init (GtkIMContextClass *class);
 static void gtk_im_context_init (GtkIMContext *im_context);
 
-static void     gtk_im_context_real_get_preedit_string (GtkIMContext       *context,
-							gchar             **str,
-							PangoAttrList     **attrs,
-							gint               *cursor_pos);
-static gboolean gtk_im_context_real_filter_keypress    (GtkIMContext       *context,
-							GdkEventKey        *event);
+static void     gtk_im_context_real_get_preedit_string (GtkIMContext   *context,
+							gchar         **str,
+							PangoAttrList **attrs,
+							gint           *cursor_pos);
+static gboolean gtk_im_context_real_filter_keypress    (GtkIMContext   *context,
+							GdkEventKey    *event);
+static gboolean gtk_im_context_real_get_surrounding    (GtkIMContext   *context,
+							gchar         **text,
+							gint           *cursor_index);
+static void     gtk_im_context_real_set_surrounding    (GtkIMContext   *context,
+							const char     *text,
+							gint            len,
+							gint            cursor_index);
 
 GtkType
 gtk_im_context_get_type (void)
@@ -77,6 +88,8 @@ gtk_im_context_class_init (GtkIMContextClass *klass)
 
   klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
   klass->filter_keypress = gtk_im_context_real_filter_keypress;
+  klass->get_surrounding = gtk_im_context_real_get_surrounding;
+  klass->set_surrounding = gtk_im_context_real_set_surrounding;
 
   im_context_signals[PREEDIT_START] =
     gtk_signal_new ("preedit_start",
@@ -110,6 +123,25 @@ gtk_im_context_class_init (GtkIMContextClass *klass)
 		    gtk_marshal_VOID__STRING,
 		    GTK_TYPE_NONE, 1,
 		    GTK_TYPE_STRING);
+
+  im_context_signals[RETRIEVE_SURROUNDING] =
+    g_signal_new ("retrieve_surrounding",
+                  GTK_CLASS_TYPE (object_class),
+                  GTK_RUN_LAST,
+                  GTK_SIGNAL_OFFSET (GtkIMContextClass, retrieve_surrounding),
+                  _gtk_boolean_handled_accumulator, NULL,
+                  gtk_marshal_BOOLEAN__VOID,
+                  GTK_TYPE_BOOL, 0);
+  im_context_signals[DELETE_SURROUNDING] =
+    g_signal_new ("delete_surrounding",
+                  GTK_CLASS_TYPE (object_class),
+                  GTK_RUN_LAST,
+                  GTK_SIGNAL_OFFSET (GtkIMContextClass, delete_surrounding),
+                  _gtk_boolean_handled_accumulator, NULL,
+                  gtk_marshal_BOOLEAN__INT_INT,
+                  GTK_TYPE_BOOL, 2,
+                  GTK_TYPE_INT,
+		  GTK_TYPE_INT);
 }
 
 static void
@@ -138,6 +170,67 @@ gtk_im_context_real_filter_keypress (GtkIMContext       *context,
   return FALSE;
 }
 
+typedef struct
+{
+  gchar *text;
+  gint cursor_index;
+} SurroundingInfo;
+
+static void
+gtk_im_context_real_set_surrounding (GtkIMContext  *context,
+				     const gchar   *text,
+				     gint           len,
+				     gint           cursor_index)
+{
+  SurroundingInfo *info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
+
+  if (info)
+    {
+      g_free (info->text);
+      info->text = g_strndup (text, len);
+      info->cursor_index = cursor_index;
+    }
+}
+
+static gboolean
+gtk_im_context_real_get_surrounding (GtkIMContext *context,
+				     gchar       **text,
+				     gint         *cursor_index)
+{
+  gboolean result;
+  gboolean info_is_local = FALSE;
+  SurroundingInfo local_info = { NULL, 0 };
+  SurroundingInfo *info;
+  
+  info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
+  if (!info)
+    {
+      info = &local_info;
+      g_object_set_data (G_OBJECT (context), "gtk-im-surrounding-info", info);
+      info_is_local = TRUE;
+    }
+  
+  g_signal_emit (context,
+		 im_context_signals[RETRIEVE_SURROUNDING], 0,
+		 &result);
+
+  if (result)
+    {
+      *text = g_strdup (info->text ? info->text : "");
+      *cursor_index = info->cursor_index;
+    }
+  else
+    {
+      *text = NULL;
+      *cursor_index = 0;
+    }
+
+  if (info_is_local)
+    g_free (info->text);
+  
+  return result;
+}
+
 /**
  * gtk_im_context_set_client_window:
  * @context: a #GtkIMContext
@@ -324,3 +417,133 @@ gtk_im_context_set_use_preedit (GtkIMContext *context,
   if (klass->set_use_preedit)
     klass->set_use_preedit (context, use_preedit);
 }
+
+/**
+ * gtk_im_context_set_surrounding:
+ * @context: a #GtkIMContext 
+ * @text: text surrounding the insertion point, as UTF-8.
+ *        the preedit string should not be included within
+ *        @text.
+ * @len: the length of @text, or -1 if @text is nul-terminated
+ * @cursor_index: the byte index of the insertion cursor within @text.
+ * 
+ * Sets surrounding context around the insertion point and preedit
+ * string. This function is expected to be called in response to the
+ * GtkIMContext::retrieve_context signal, and will likely have no
+ * effect if called at other times.
+ **/
+void
+gtk_im_context_set_surrounding (GtkIMContext  *context,
+				const gchar   *text,
+				gint           len,
+				gint           cursor_index)
+{
+  GtkIMContextClass *klass;
+  
+  g_return_if_fail (GTK_IS_IM_CONTEXT (context));
+  g_return_if_fail (text != NULL || len == 0);
+
+  if (text == NULL && len == 0)
+    text = "";
+  if (len < 0)
+    len = strlen (text);
+
+  g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
+
+  klass = GTK_IM_CONTEXT_GET_CLASS (context);
+  if (klass->set_surrounding)
+    klass->set_surrounding (context, text, len, cursor_index);
+}
+
+/**
+ * gtk_im_context_get_surrounding:
+ * @context: a #GtkIMContext
+ * @text: location to store a UTF-8 encoded string of text
+ *        holding context around the insertion point.
+ *        If the function returns %TRUE, then you must free
+ *        the result stored in this location with g_free().
+ * @cursor_index: location to store byte index of the insertion cursor
+ *        within @text.
+ * 
+ * Retrieves context around the insertion point. 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
+ * GtkIMContext::retrieve_context 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
+ * gtk_im_context_set_surrounding. Note that there is no obligation
+ * for a widget to respond to the ::retrieve_context signal, so input
+ * methods must be prepared to function without context.
+ *
+ * Return value: %TRUE if surrounding text was provided; in this case
+ *    you must free the result stored in *text.
+ **/
+gboolean
+gtk_im_context_get_surrounding (GtkIMContext *context,
+				gchar       **text,
+				gint         *cursor_index)
+{
+  GtkIMContextClass *klass;
+  gchar *local_text = NULL;
+  gint local_index;
+  gboolean result = FALSE;
+  
+  g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
+
+  klass = GTK_IM_CONTEXT_GET_CLASS (context);
+  if (klass->get_surrounding)
+    result = klass->get_surrounding (context,
+				     text ? text : &local_text,
+				     cursor_index ? cursor_index : &local_index);
+
+  if (result)
+    g_free (local_text);
+
+  return result;
+}
+
+/**
+ * gtk_im_context_delete_surrounding:
+ * @context: a #GtkIMContext
+ * @offset: offset from cursor position in chars;
+ *    a negative value means start before the cursor.
+ * @n_chars: number of characters to delete.
+ * 
+ * Asks the widget that the input context is attached to to delete
+ * characters around the cursor position by emitting the
+ * GtkIMContext::delete_context signal. 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
+ * gtk_im_context_get_surrounding() to get the current context, and
+ * call this function immediately afterwards 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
+ * subsitutions in the existing text in response to new input. It is
+ * not useful for applications.
+ * 
+ * Return value: %TRUE if the signal was handled.
+ **/
+gboolean
+gtk_im_context_delete_surrounding (GtkIMContext *context,
+				   gint          offset,
+				   gint          n_chars)
+{
+  gboolean result;
+  
+  g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
+
+  g_signal_emit (context,
+		 im_context_signals[DELETE_SURROUNDING], 0,
+		 offset, n_chars, &result);
+
+  return result;
+}
+