path: root/docs/reference/pygtk-gtkimcontext.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="class-gtkimcontext">
  <refmeta>
    <refentrytitle>gtk.IMContext</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>PyGTK Docs</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>gtk.IMContext</refname>
    <refpurpose>an abstract base class defining a generic input method
interface</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IMContext</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkobject">gtk.Object</link></classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--set-client-window">set_client_window</link></methodname>
	<methodparam><parameter
		       role="keyword">window</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--get-preedit-string">get_preedit_string</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--filter-keypress">filter_keypress</link></methodname>
	<methodparam><parameter role="keyword">key</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--focus-in">focus_in</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--focus-out">focus_out</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--reset">reset</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--set-cursor-location">set_cursor_location</link></methodname>
	<methodparam><parameter
		       role="keyword">area</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--set-use-preedit">set_use_preedit</link></methodname>
	<methodparam><parameter
		       role="keyword">use_preedit</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--set-surrounding">set_surrounding</link></methodname>
	<methodparam><parameter
		       role="keyword">text</parameter></methodparam>
	<methodparam><parameter role="keyword">len</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">cursor_index</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--get-surrounding">get_surrounding</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimcontext--delete-surrounding">delete_surrounding</link></methodname>
	<methodparam><parameter
		       role="keyword">offset</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkimcontext">gtk.IMContext</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkimcontext">
    <title>gtk.IMContext Signal Prototypes</title>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--commit">commit</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>string</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--delete-surrounding">delete-surrounding</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>offset</parameter>
            </methodparam>
            <methodparam><parameter>n_chars</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--preedit-changed">preedit-changed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--preedit-end">preedit-end</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--preedit-start">preedit-start</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkimcontext--retrieve-surrounding">retrieve-surrounding</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>imcontext</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkimcontext"><classname>gtk.IMContext</classname></link> is
an abstract base class used to provide objects to manage the context for
input methods used to support text input in various natural languages. The
character input for some languages (e.g. Chinese, Japanese and Korean)
cannot be easily input using standard keyboards so multiple keystrokes are
used to input a single character. Input methods are used to help this
process by providing feedback of the characters input and managing the
context and valid combinations. The<link
linkend="class-gtkimcontext"><classname>gtk.IMContext</classname></link>
subclasses manage the required context information for applications and
widgets such as the <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> and <link
linkend="class-gtktextview"><classname>gtk.TextView</classname></link>
widgets.</para>

    <para>The <link
linkend="class-gtkimcontext"><classname>gtk.IMContext</classname></link>
manages the context of the text surrounding the cursor and the preedit text
that provides feedback about the in-process multiple character
composition.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkimcontext--set-client-window">
      <title>gtk.IMContext.set_client_window</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_client_window</methodname>
	  <methodparam><parameter
			 role="keyword">window</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">window</parameter>&nbsp;:</term>
	  <listitem><simpara>the client window. This may be
<literal>None</literal> to indicate that the previous client window no
longer exists.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_client_window</methodname>() method set the
client window for the input context; this is the <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> in
which the input appears. This window is used in order to correctly position
status windows, and may also be used for purposes internal to the input
method.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--get-preedit-string">
      <title>gtk.IMContext.get_preedit_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_preedit_string</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the preedit string, the
attribute list and the position of cursor (in bytes) within the preedit
string.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_preedit_string</methodname>() method returns
a tuple containing: the current preedit string for the input context, a list
of attributes to apply to the string and the cursor position within the
string. This string should be displayed inserted at the insertion
point.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--filter-keypress">
      <title>gtk.IMContext.filter_keypress</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>filter_keypress</methodname>
	  <methodparam><parameter
			 role="keyword">event</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">key</parameter>&nbsp;:</term>
	  <listitem><simpara>the key event</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the input method
handled the keystroke.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>filter_keypress</methodname>() method allows an
input method to internally handle a key press event. If this function
returns <literal>True</literal>, then no further processing should be done
for this keystroke.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--focus-in">
      <title>gtk.IMContext.focus_in</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>focus_in</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>focus_in</methodname>() method notifies the
input method that the widget to which this input context corresponds has
gained focus. The input method may, for example, change the displayed
feedback to reflect this change.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--focus-out">
      <title>gtk.IMContext.focus_out</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>focus_out</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>focus_out</methodname>() method notifies the
input method that the widget to which this input context corresponds has
lost focus. The input method may, for example, change the displayed feedback
or reset the context state to reflect this change.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--reset">
      <title>gtk.IMContext.reset</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>reset</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>reset</methodname>() method notifies the input
method that a significant change in context (such as a change in cursor
position) has been made. This will typically cause the input method to clear
the preedit state.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--set-cursor-location">
      <title>gtk.IMContext.set_cursor_location</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_cursor_location</methodname>
	  <methodparam><parameter
			 role="keyword">area</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">area</parameter>&nbsp;:</term>
	  <listitem><simpara>new location</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_cursor_location</methodname>() method
notifies the input method that a change in cursor position has been
made.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--set-use-preedit">
      <title>gtk.IMContext.set_use_preedit</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_preedit</methodname>
	  <methodparam><parameter
			 role="keyword">use_preedit</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">use_preedit</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the IM context
should use the preedit string.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_use_preedit</methodname>() method sets the
use preedit setting to the value of use_preedit. If
<parameter>use_preedit</parameter> is <literal>True</literal> (the default)
the IM context should use the preedit string to display feedback. If
<parameter>use_preedit</parameter> is <literal>False</literal> the IM
context may use some other method to display feedback, such as displaying it
in a child of the root window.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--set-surrounding">
      <title>gtk.IMContext.set_surrounding</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_surrounding</methodname>
	  <methodparam><parameter
			 role="keyword">text</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">len</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">cursor_index</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">text</parameter>&nbsp;:</term>
	  <listitem><simpara>the text surrounding the insertion point, as
UTF-8. the preedit string should not be included within
it.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">len</parameter>&nbsp;:</term>
	  <listitem><simpara>the length of <parameter>text</parameter>, or
-1 to calculate the length of
<parameter>text</parameter>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">cursor_index</parameter>&nbsp;:</term>
	  <listitem><simpara>the byte index of the insertion cursor within
<parameter>text</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_surrounding</methodname>() method sets
surrounding context around the insertion point and preedit string. This
function is expected to be called in response to the "retrieve_surrounding"
signal, and will likely have no effect if called at other times.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--get-surrounding">
      <title>gtk.IMContext.get_surrounding</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_surrounding</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the UTF-8 encoded string of
text holding context around the insertion point and the byte index of the
insertion cursor within the string, or None if no surrounding context was
retrieved.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_surrounding</methodname>() method returns a
tuple containing the text surrounding the cursor and the byte index of the
cursor within the text. 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.</para>

      <para>This function is implemented by emitting the
"retrieve_surrounding" 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 <link
linkend="method-gtkimcontext--set-surrounding"><methodname>set_surrounding</methodname>()</link>. 
Note that there is no obligation for a widget to respond to the
"retrieve_surrounding" signal, so input methods must be prepared to function
without context.</para>

    </refsect2>

    <refsect2 id="method-gtkimcontext--delete-surrounding">
      <title>gtk.IMContext.delete_surrounding</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>delete_surrounding</methodname>
	  <methodparam><parameter
			 role="keyword">offset</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">n_chars</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">offset</parameter>&nbsp;:</term>
	  <listitem><simpara>the offset from cursor position in chars; a
negative value means start before the cursor.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of characters to
delete.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the signal was
handled.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The delete_surrounding() method asks the widget that the input
context is attached to to delete characters around the cursor position by
emitting the "delete_surrounding" signal. Note that
<parameter>offset</parameter> and <parameter>n_chars</parameter> are in
characters not in bytes, which differs from the usage other places in the
<link
linkend="class-gtkimcontext"><classname>gtk.IMContext</classname></link>
class.</para>

      <para>In order to use this function, you should first call <link
linkend="method-gtkimcontext--get-surrounding"><methodname>get_surrounding</methodname>()</link> 
to get the current context, and call this function immediately afterward 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.</para>

      <para>This function is used by an input method that wants to make
substitutions in the existing text in response to new input. It is not useful
for applications.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkimcontext--commit">
      <title>The "commit" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>string</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>string</parameter>&nbsp;:</term>
	  <listitem><simpara>the text to be committed</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "commit" signal is emitted when the text is ready to be
displayed.</para>

    </refsect2>

    <refsect2 id="signal-gtkimcontext--delete-surrounding">
      <title>The "delete-surrounding" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>offset</parameter>&nbsp;:</term>
	  <listitem><simpara>the offset from the cursor position of the text
to be deleted</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>n_chars</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of characters to be
deleted</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the signal was
handled.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "delete-surrounding" signal is emitted when the input method
needs to delete the context text.</para>

    </refsect2>

    <refsect2 id="signal-gtkimcontext--preedit-changed">
      <title>The "preedit-changed" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "preedit-changed" signal is emitted when the preedit text
has changed.</para>

    </refsect2>

    <refsect2 id="signal-gtkimcontext--preedit-end">
      <title>The "preedit-end" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "preedit-end" signal is emitted when preediting is
completed.</para>

    </refsect2>

    <refsect2 id="signal-gtkimcontext--preedit-start">
      <title>The "preedit-start" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "preedit-start" signal is emitted when preediting is
started.</para>

    </refsect2>

    <refsect2 id="signal-gtkimcontext--retrieve-surrounding">
      <title>The "retrieve-surrounding" gtk.IMContext Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>imcontext</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>imcontext</parameter>&nbsp;:</term>
	  <listitem><simpara>the imcontext that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the signal was
handled.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>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 <link
linkend="method-gtkimcontext--set-surrounding"><methodname>set_surrounding</methodname>()</link> 
method. The method returns <literal>True</literal> if the signal was handled
by the callback.</para>

    </refsect2>

  </refsect1>

</refentry>