← Back to branch summary

~canonical-dx-team/ubuntu/maverick/gtk+2.0/menuproxy

« back to all changes in this revision

Viewing changes to docs/reference/gtk/xml/gtkimcontext.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2007-05-04 12:24:25 UTC
  • mfrom: (1.1.21 upstream)
  • Revision ID: james.westby@ubuntu.com-20070504122425-0m8midgzrp40y8w2
Tags: 2.10.12-1ubuntu1
* Sync with Debian
* New upstream version:
  Fixed bugs:
  - 379414 file chooser warnings when changing path in the entry
  - 418585 GtkFileChooserDefault sizing code is not DPI independent
  - 419568 Crash in search if start with special letter
  - 435062 build dies with icon cache validation
  - 379399 Segfault to call gtk_print_operation_run twice.
  - 387889 cups backend has problems when there are too many printers
  - 418531 invalid read to gtkicontheme.c gtk_icon_theme_lookup_icon...
  - 423916 crash in color scheme code
  - 424042 Segmentation fault while quickly pressing Alt+arrows
  - 415260 Protect against negative indices when setting values in G...
  - 419171 XGetVisualInfo() may not set nxvisuals
  - 128852 Gdk cursors don't look good on win32
  - 344657 Ctrl-H doesn't toggle "Show Hidden Files" setting
  - 345345 PrintOperation::paginate is not emitted for class handler
  - 347567 GtkPrintOperation::end-print is not emitted if it's cance...
  - 369112 gtk_ui_manager_add_ui should accept unnamed separator
  - 392015 Selected menu item invisible on Windows Vista
  - 399253 MS-Windows Theme Bottom Tab placement rendering glitches
  - 399425 gtk_input_dialog_fill_axes() adds child to gtkscrolledwin...
  - 403251 [patch] little memory leak in GtkPrintJob
  - 403267 [patch] memory leak in GtkPageSetupUnixDialog
  - 403470 MS-Windows Theme tab placement other than on top leaks a ...
  - 404506 Windows system fonts that have multi-byte font names cann...
  - 405089 Incorrect window placement for GtkEventBox private window
  - 405515 Minor leak in gtkfilesystemmodel.c
  - 405539 gdk_pixbuf_save() for PNG saver can return FALSE without ...
  - 415681 gdk_window_clear_area includes an extra line and column o...
  - 418219 GtkRecentChooser should apply filter before sorting and c...
  - 418403 Scroll to printer after selecting it from settings
  - 421985 _gtk_print_operation_platform_backend_launch_preview
  - 421990 gtk_print_job_get_surface
  - 421993 gtk_print_operation_init
  - 423064 Conditional jump or move depends on uninitialised value(s...
  - 423722 Fix printing header in gtk-demo
  - 424168 gtk_print_operation_run on async preview
  - 425655 Don't install gtk+-unix-print-2.0.pc on non-UNIX platforms
  - 425786 GDK segfaults if XineramaQueryScreens fails
  - 428665 Lpr Backend gets stuck in infinite loop during gtk_enumer...
  - 429902 GtkPrintOperation leaks cairo contextes
  - 431997 First delay of GdkPixbufAnimationIter is wrong
  - 433242 Inconsistent scroll arrow position calculations
  - 433972 Placing gtk.Expander inside a gtk.TextView() changes gtk....
  - 434261 _gtk_toolbar_elide_underscores incorrectly handles some s...
  - 383354 ctrl-L should make 'Location' entry disappear
  - 418673 gtk_recent_manager_add_item
  - 429732 gtk_accel_group_finalize accesses invalid memory
  - 435028 WM_CLIENT_LEADER is wrong on the leader_window
  - 431067 Background of the header window is not updated
  - 338843 add recent files support inside the ui manager
  - 148535 add drop shadow to menus, tooltips, etc. under Windows XP
* debian/control.in:
  - Conflicts on ubuntulooks (<= 0.9.11-1)
* debian/patches/15_default-fallback-icon-theme.patch:
  - patch from Debian, fallback on gnome icon theme

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gtk/xml/gtkimcontext.xml
 
1
<refentry id="GtkIMContext">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page">GtkIMContext</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>GTK Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>GtkIMContext</refname>
 
10
<refpurpose>Base class for input method contexts</refpurpose>
 
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
12
</refnamediv>
 
13
 
 
14
<refsynopsisdiv role="synopsis">
 
15
<title role="synopsis.title">Synopsis</title>
 
16
 
 
17
<synopsis>
 
18
 
 
19
#include &lt;gtk/gtk.h&gt;
 
20
 
 
21
 
 
22
                    <link linkend="GtkIMContext-struct">GtkIMContext</link>;
 
23
<link linkend="void">void</link>                <link linkend="gtk-im-context-set-client-window">gtk_im_context_set_client_window</link>    (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
24
                                                         <link linkend="GdkWindow">GdkWindow</link> *window);
 
25
<link linkend="void">void</link>                <link linkend="gtk-im-context-get-preedit-string">gtk_im_context_get_preedit_string</link>   (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
26
                                                         <link linkend="gchar">gchar</link> **str,
 
27
                                                         <link linkend="PangoAttrList">PangoAttrList</link> **attrs,
 
28
                                                         <link linkend="gint">gint</link> *cursor_pos);
 
29
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-im-context-filter-keypress">gtk_im_context_filter_keypress</link>      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
30
                                                         <link linkend="GdkEventKey">GdkEventKey</link> *event);
 
31
<link linkend="void">void</link>                <link linkend="gtk-im-context-focus-in">gtk_im_context_focus_in</link>             (<link linkend="GtkIMContext">GtkIMContext</link> *context);
 
32
<link linkend="void">void</link>                <link linkend="gtk-im-context-focus-out">gtk_im_context_focus_out</link>            (<link linkend="GtkIMContext">GtkIMContext</link> *context);
 
33
<link linkend="void">void</link>                <link linkend="gtk-im-context-reset">gtk_im_context_reset</link>                (<link linkend="GtkIMContext">GtkIMContext</link> *context);
 
34
<link linkend="void">void</link>                <link linkend="gtk-im-context-set-cursor-location">gtk_im_context_set_cursor_location</link>  (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
35
                                                         <link linkend="GdkRectangle">GdkRectangle</link> *area);
 
36
<link linkend="void">void</link>                <link linkend="gtk-im-context-set-use-preedit">gtk_im_context_set_use_preedit</link>      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
37
                                                         <link linkend="gboolean">gboolean</link> use_preedit);
 
38
<link linkend="void">void</link>                <link linkend="gtk-im-context-set-surrounding">gtk_im_context_set_surrounding</link>      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
39
                                                         const <link linkend="gchar">gchar</link> *text,
 
40
                                                         <link linkend="gint">gint</link> len,
 
41
                                                         <link linkend="gint">gint</link> cursor_index);
 
42
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-im-context-get-surrounding">gtk_im_context_get_surrounding</link>      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
43
                                                         <link linkend="gchar">gchar</link> **text,
 
44
                                                         <link linkend="gint">gint</link> *cursor_index);
 
45
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-im-context-delete-surrounding">gtk_im_context_delete_surrounding</link>   (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
46
                                                         <link linkend="gint">gint</link> offset,
 
47
                                                         <link linkend="gint">gint</link> n_chars);
 
48
 
 
49
 
 
50
</synopsis>
 
51
</refsynopsisdiv>
 
52
 
 
53
<refsect1 role="object_hierarchy">
 
54
<title role="object_hierarchy.title">Object Hierarchy</title>
 
55
<synopsis>
 
56
 
 
57
  <link linkend="GObject">GObject</link>
 
58
   +----GtkIMContext
 
59
         +----<link linkend="GtkIMContextSimple">GtkIMContextSimple</link>
 
60
         +----<link linkend="GtkIMMulticontext">GtkIMMulticontext</link>
 
61
</synopsis>
 
62
 
 
63
</refsect1>
 
64
 
 
65
 
 
66
 
 
67
 
 
68
 
 
69
 
 
70
<refsect1 role="signal_proto">
 
71
<title role="signal_proto.title">Signals</title>
 
72
<synopsis>
 
73
 
 
74
  &quot;<link linkend="GtkIMContext-commit">commit</link>&quot;                                         : Run Last
 
75
  &quot;<link linkend="GtkIMContext-delete-surrounding">delete-surrounding</link>&quot;                             : Run Last
 
76
  &quot;<link linkend="GtkIMContext-preedit-changed">preedit-changed</link>&quot;                                : Run Last
 
77
  &quot;<link linkend="GtkIMContext-preedit-end">preedit-end</link>&quot;                                    : Run Last
 
78
  &quot;<link linkend="GtkIMContext-preedit-start">preedit-start</link>&quot;                                  : Run Last
 
79
  &quot;<link linkend="GtkIMContext-retrieve-surrounding">retrieve-surrounding</link>&quot;                           : Run Last
 
80
</synopsis>
 
81
</refsect1>
 
82
 
 
83
 
 
84
<refsect1 role="desc">
 
85
<title role="desc.title">Description</title>
 
86
<para>
 
87
 
 
88
</para>
 
89
</refsect1>
 
90
 
 
91
<refsect1 role="details">
 
92
<title role="details.title">Details</title>
 
93
<refsect2>
 
94
<title><anchor id="GtkIMContext-struct" role="struct"/>GtkIMContext</title>
 
95
<indexterm><primary>GtkIMContext</primary></indexterm><programlisting>typedef struct _GtkIMContext GtkIMContext;</programlisting>
 
96
<para>
 
97
 
 
98
</para></refsect2>
 
99
<refsect2>
 
100
<title><anchor id="gtk-im-context-set-client-window" role="function"/>gtk_im_context_set_client_window ()</title>
 
101
<indexterm><primary>gtk_im_context_set_client_window</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_set_client_window    (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
102
                                                         <link linkend="GdkWindow">GdkWindow</link> *window);</programlisting>
 
103
<para>
 
104
Set the client window for the input context; this is the
 
105
<link linkend="GdkWindow"><type>GdkWindow</type></link> in which the input appears. This window is
 
106
used in order to correctly position status windows, and may
 
107
also be used for purposes internal to the input method.</para>
 
108
<para>
 
109
 
 
110
</para><variablelist role="params">
 
111
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
112
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
113
</simpara></listitem></varlistentry>
 
114
<varlistentry><term><parameter>window</parameter>&nbsp;:</term>
 
115
<listitem><simpara>  the client window. This may be <link linkend="NULL:CAPS"><literal>NULL</literal></link> to indicate
 
116
          that the previous client window no longer exists.
 
117
</simpara></listitem></varlistentry>
 
118
</variablelist></refsect2>
 
119
<refsect2>
 
120
<title><anchor id="gtk-im-context-get-preedit-string" role="function"/>gtk_im_context_get_preedit_string ()</title>
 
121
<indexterm><primary>gtk_im_context_get_preedit_string</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_get_preedit_string   (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
122
                                                         <link linkend="gchar">gchar</link> **str,
 
123
                                                         <link linkend="PangoAttrList">PangoAttrList</link> **attrs,
 
124
                                                         <link linkend="gint">gint</link> *cursor_pos);</programlisting>
 
125
<para>
 
126
Retrieve the current preedit string for the input context,
 
127
and a list of attributes to apply to the string.
 
128
This string should be displayed inserted at the insertion
 
129
point.</para>
 
130
<para>
 
131
 
 
132
</para><variablelist role="params">
 
133
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
134
<listitem><simpara>    a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
135
</simpara></listitem></varlistentry>
 
136
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
 
137
<listitem><simpara>        location to store the retrieved string. The
 
138
             string retrieved must be freed with <link linkend="g-free"><function>g_free()</function></link>.
 
139
</simpara></listitem></varlistentry>
 
140
<varlistentry><term><parameter>attrs</parameter>&nbsp;:</term>
 
141
<listitem><simpara>      location to store the retrieved attribute list.
 
142
             When you are done with this list, you must
 
143
             unreference it with <link linkend="pango-attr-list-unref"><function>pango_attr_list_unref()</function></link>.
 
144
</simpara></listitem></varlistentry>
 
145
<varlistentry><term><parameter>cursor_pos</parameter>&nbsp;:</term>
 
146
<listitem><simpara> location to store position of cursor (in characters)
 
147
             within the preedit string.  
 
148
</simpara></listitem></varlistentry>
 
149
</variablelist></refsect2>
 
150
<refsect2>
 
151
<title><anchor id="gtk-im-context-filter-keypress" role="function"/>gtk_im_context_filter_keypress ()</title>
 
152
<indexterm><primary>gtk_im_context_filter_keypress</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_im_context_filter_keypress      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
153
                                                         <link linkend="GdkEventKey">GdkEventKey</link> *event);</programlisting>
 
154
<para>
 
155
Allow an input method to internally handle key press and release 
 
156
events. If this function returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, then no further processing
 
157
should be done for this key event.</para>
 
158
<para>
 
159
 
 
160
</para><variablelist role="params">
 
161
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
162
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
163
</simpara></listitem></varlistentry>
 
164
<varlistentry><term><parameter>event</parameter>&nbsp;:</term>
 
165
<listitem><simpara> the key event
 
166
</simpara></listitem></varlistentry>
 
167
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the input method handled the key event.
 
168
 
 
169
</simpara></listitem></varlistentry>
 
170
</variablelist></refsect2>
 
171
<refsect2>
 
172
<title><anchor id="gtk-im-context-focus-in" role="function"/>gtk_im_context_focus_in ()</title>
 
173
<indexterm><primary>gtk_im_context_focus_in</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_focus_in             (<link linkend="GtkIMContext">GtkIMContext</link> *context);</programlisting>
 
174
<para>
 
175
Notify the input method that the widget to which this
 
176
input context corresponds has gained focus. The input method
 
177
may, for example, change the displayed feedback to reflect
 
178
this change.</para>
 
179
<para>
 
180
 
 
181
</para><variablelist role="params">
 
182
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
183
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
184
</simpara></listitem></varlistentry>
 
185
</variablelist></refsect2>
 
186
<refsect2>
 
187
<title><anchor id="gtk-im-context-focus-out" role="function"/>gtk_im_context_focus_out ()</title>
 
188
<indexterm><primary>gtk_im_context_focus_out</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_focus_out            (<link linkend="GtkIMContext">GtkIMContext</link> *context);</programlisting>
 
189
<para>
 
190
Notify the input method that the widget to which this
 
191
input context corresponds has lost focus. The input method
 
192
may, for example, change the displayed feedback or reset the contexts
 
193
state to reflect this change.</para>
 
194
<para>
 
195
 
 
196
</para><variablelist role="params">
 
197
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
198
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
199
</simpara></listitem></varlistentry>
 
200
</variablelist></refsect2>
 
201
<refsect2>
 
202
<title><anchor id="gtk-im-context-reset" role="function"/>gtk_im_context_reset ()</title>
 
203
<indexterm><primary>gtk_im_context_reset</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_reset                (<link linkend="GtkIMContext">GtkIMContext</link> *context);</programlisting>
 
204
<para>
 
205
Notify the input method that a change such as a change in cursor
 
206
position has been made. This will typically cause the input
 
207
method to clear the preedit state.</para>
 
208
<para>
 
209
 
 
210
</para><variablelist role="params">
 
211
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
212
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
213
</simpara></listitem></varlistentry>
 
214
</variablelist></refsect2>
 
215
<refsect2>
 
216
<title><anchor id="gtk-im-context-set-cursor-location" role="function"/>gtk_im_context_set_cursor_location ()</title>
 
217
<indexterm><primary>gtk_im_context_set_cursor_location</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_set_cursor_location  (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
218
                                                         <link linkend="GdkRectangle">GdkRectangle</link> *area);</programlisting>
 
219
<para>
 
220
Notify the input method that a change in cursor 
 
221
position has been made. The location is relative to the client
 
222
window.</para>
 
223
<para>
 
224
 
 
225
</para><variablelist role="params">
 
226
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
227
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
228
</simpara></listitem></varlistentry>
 
229
<varlistentry><term><parameter>area</parameter>&nbsp;:</term>
 
230
<listitem><simpara> new location
 
231
</simpara></listitem></varlistentry>
 
232
</variablelist></refsect2>
 
233
<refsect2>
 
234
<title><anchor id="gtk-im-context-set-use-preedit" role="function"/>gtk_im_context_set_use_preedit ()</title>
 
235
<indexterm><primary>gtk_im_context_set_use_preedit</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_set_use_preedit      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
236
                                                         <link linkend="gboolean">gboolean</link> use_preedit);</programlisting>
 
237
<para>
 
238
Sets whether the IM context should use the preedit string
 
239
to display feedback. If <parameter>use_preedit</parameter> is FALSE (default
 
240
is TRUE), then the IM context may use some other method to display
 
241
feedback, such as displaying it in a child of the root window.</para>
 
242
<para>
 
243
 
 
244
</para><variablelist role="params">
 
245
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
246
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
247
</simpara></listitem></varlistentry>
 
248
<varlistentry><term><parameter>use_preedit</parameter>&nbsp;:</term>
 
249
<listitem><simpara> whether the IM context should use the preedit string.
 
250
</simpara></listitem></varlistentry>
 
251
</variablelist></refsect2>
 
252
<refsect2>
 
253
<title><anchor id="gtk-im-context-set-surrounding" role="function"/>gtk_im_context_set_surrounding ()</title>
 
254
<indexterm><primary>gtk_im_context_set_surrounding</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_im_context_set_surrounding      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
255
                                                         const <link linkend="gchar">gchar</link> *text,
 
256
                                                         <link linkend="gint">gint</link> len,
 
257
                                                         <link linkend="gint">gint</link> cursor_index);</programlisting>
 
258
<para>
 
259
Sets surrounding context around the insertion point and preedit
 
260
string. This function is expected to be called in response to the
 
261
GtkIMContext::retrieve_surrounding signal, and will likely have no
 
262
effect if called at other times.</para>
 
263
<para>
 
264
 
 
265
</para><variablelist role="params">
 
266
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
267
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link> 
 
268
</simpara></listitem></varlistentry>
 
269
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
 
270
<listitem><simpara> text surrounding the insertion point, as UTF-8.
 
271
       the preedit string should not be included within
 
272
       <parameter>text</parameter>.
 
273
</simpara></listitem></varlistentry>
 
274
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
 
275
<listitem><simpara> the length of <parameter>text</parameter>, or -1 if <parameter>text</parameter> is nul-terminated
 
276
</simpara></listitem></varlistentry>
 
277
<varlistentry><term><parameter>cursor_index</parameter>&nbsp;:</term>
 
278
<listitem><simpara> the byte index of the insertion cursor within <parameter>text</parameter>.
 
279
</simpara></listitem></varlistentry>
 
280
</variablelist></refsect2>
 
281
<refsect2>
 
282
<title><anchor id="gtk-im-context-get-surrounding" role="function"/>gtk_im_context_get_surrounding ()</title>
 
283
<indexterm><primary>gtk_im_context_get_surrounding</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_im_context_get_surrounding      (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
284
                                                         <link linkend="gchar">gchar</link> **text,
 
285
                                                         <link linkend="gint">gint</link> *cursor_index);</programlisting>
 
286
<para>
 
287
Retrieves context around the insertion point. Input methods
 
288
typically want context in order to constrain input text based on
 
289
existing text; this is important for languages such as Thai where
 
290
only some sequences of characters are allowed.
 
291
</para>
 
292
<para>
 
293
This function is implemented by emitting the
 
294
GtkIMContext::retrieve_surrounding signal on the input method; in
 
295
response to this signal, a widget should provide as much context as
 
296
is available, up to an entire paragraph, by calling
 
297
<link linkend="gtk-im-context-set-surrounding"><function>gtk_im_context_set_surrounding()</function></link>. Note that there is no obligation
 
298
for a widget to respond to the ::retrieve_surrounding signal, so input
 
299
methods must be prepared to function without context.</para>
 
300
<para>
 
301
 
 
302
</para><variablelist role="params">
 
303
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
304
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
305
</simpara></listitem></varlistentry>
 
306
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
 
307
<listitem><simpara> location to store a UTF-8 encoded string of text
 
308
       holding context around the insertion point.
 
309
       If the function returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, then you must free
 
310
       the result stored in this location with <link linkend="g-free"><function>g_free()</function></link>.
 
311
</simpara></listitem></varlistentry>
 
312
<varlistentry><term><parameter>cursor_index</parameter>&nbsp;:</term>
 
313
<listitem><simpara> location to store byte index of the insertion cursor
 
314
       within <parameter>text</parameter>.
 
315
</simpara></listitem></varlistentry>
 
316
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if surrounding text was provided; in this case
 
317
   you must free the result stored in *text.
 
318
</simpara></listitem></varlistentry>
 
319
</variablelist></refsect2>
 
320
<refsect2>
 
321
<title><anchor id="gtk-im-context-delete-surrounding" role="function"/>gtk_im_context_delete_surrounding ()</title>
 
322
<indexterm><primary>gtk_im_context_delete_surrounding</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_im_context_delete_surrounding   (<link linkend="GtkIMContext">GtkIMContext</link> *context,
 
323
                                                         <link linkend="gint">gint</link> offset,
 
324
                                                         <link linkend="gint">gint</link> n_chars);</programlisting>
 
325
<para>
 
326
Asks the widget that the input context is attached to to delete
 
327
characters around the cursor position by emitting the
 
328
GtkIMContext::delete_surrounding signal. Note that <parameter>offset</parameter> and <parameter>n_chars</parameter>
 
329
are in characters not in bytes which differs from the usage other
 
330
places in <link linkend="GtkIMContext"><type>GtkIMContext</type></link>.
 
331
</para>
 
332
<para>
 
333
In order to use this function, you should first call
 
334
<link linkend="gtk-im-context-get-surrounding"><function>gtk_im_context_get_surrounding()</function></link> to get the current context, and
 
335
call this function immediately afterwards to make sure that you
 
336
know what you are deleting. You should also account for the fact
 
337
that even if the signal was handled, the input context might not
 
338
have deleted all the characters that were requested to be deleted.
 
339
</para>
 
340
<para>
 
341
This function is used by an input method that wants to make
 
342
subsitutions in the existing text in response to new input. It is
 
343
not useful for applications.</para>
 
344
<para>
 
345
 
 
346
</para><variablelist role="params">
 
347
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
348
<listitem><simpara> a <link linkend="GtkIMContext"><type>GtkIMContext</type></link>
 
349
</simpara></listitem></varlistentry>
 
350
<varlistentry><term><parameter>offset</parameter>&nbsp;:</term>
 
351
<listitem><simpara> offset from cursor position in chars;
 
352
   a negative value means start before the cursor.
 
353
</simpara></listitem></varlistentry>
 
354
<varlistentry><term><parameter>n_chars</parameter>&nbsp;:</term>
 
355
<listitem><simpara> number of characters to delete.
 
356
</simpara></listitem></varlistentry>
 
357
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the signal was handled.
 
358
</simpara></listitem></varlistentry>
 
359
</variablelist></refsect2>
 
360
 
 
361
</refsect1>
 
362
 
 
363
<refsect1 role="signals">
 
364
<title role="signals.title">Signal Details</title>
 
365
<refsect2><title><anchor id="GtkIMContext-commit"/>The &quot;commit&quot; signal</title>
 
366
<indexterm><primary>GtkIMContext::commit</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
367
                                                        <link linkend="gchar">gchar</link>        *arg1,
 
368
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
369
<para>
 
370
 
 
371
</para><variablelist role="params">
 
372
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
373
<listitem><simpara>the object which received the signal.
 
374
</simpara></listitem></varlistentry>
 
375
<varlistentry><term><parameter>arg1</parameter>&nbsp;:</term>
 
376
<listitem><simpara>
 
377
 
 
378
</simpara></listitem></varlistentry>
 
379
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
380
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
381
</variablelist></refsect2><refsect2><title><anchor id="GtkIMContext-delete-surrounding"/>The &quot;delete-surrounding&quot; signal</title>
 
382
<indexterm><primary>GtkIMContext::delete-surrounding</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
383
                                                        <link linkend="gint">gint</link>          arg1,
 
384
                                                        <link linkend="gint">gint</link>          arg2,
 
385
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
386
<para>
 
387
 
 
388
</para><variablelist role="params">
 
389
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
390
<listitem><simpara>the object which received the signal.
 
391
</simpara></listitem></varlistentry>
 
392
<varlistentry><term><parameter>arg1</parameter>&nbsp;:</term>
 
393
<listitem><simpara>
 
394
</simpara></listitem></varlistentry>
 
395
<varlistentry><term><parameter>arg2</parameter>&nbsp;:</term>
 
396
<listitem><simpara>
 
397
</simpara></listitem></varlistentry>
 
398
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
399
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
400
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
 
401
 
 
402
</simpara></listitem></varlistentry>
 
403
</variablelist></refsect2><refsect2><title><anchor id="GtkIMContext-preedit-changed"/>The &quot;preedit-changed&quot; signal</title>
 
404
<indexterm><primary>GtkIMContext::preedit-changed</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
405
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
406
<para>
 
407
 
 
408
</para><variablelist role="params">
 
409
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
410
<listitem><simpara>the object which received the signal.
 
411
 
 
412
</simpara></listitem></varlistentry>
 
413
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
414
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
415
</variablelist></refsect2><refsect2><title><anchor id="GtkIMContext-preedit-end"/>The &quot;preedit-end&quot; signal</title>
 
416
<indexterm><primary>GtkIMContext::preedit-end</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
417
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
418
<para>
 
419
 
 
420
</para><variablelist role="params">
 
421
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
422
<listitem><simpara>the object which received the signal.
 
423
 
 
424
</simpara></listitem></varlistentry>
 
425
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
426
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
427
</variablelist></refsect2><refsect2><title><anchor id="GtkIMContext-preedit-start"/>The &quot;preedit-start&quot; signal</title>
 
428
<indexterm><primary>GtkIMContext::preedit-start</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
429
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
430
<para>
 
431
 
 
432
</para><variablelist role="params">
 
433
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
434
<listitem><simpara>the object which received the signal.
 
435
 
 
436
</simpara></listitem></varlistentry>
 
437
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
438
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
439
</variablelist></refsect2><refsect2><title><anchor id="GtkIMContext-retrieve-surrounding"/>The &quot;retrieve-surrounding&quot; signal</title>
 
440
<indexterm><primary>GtkIMContext::retrieve-surrounding</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            user_function                      (<link linkend="GtkIMContext">GtkIMContext</link> *imcontext,
 
441
                                                        <link linkend="gpointer">gpointer</link>      user_data)      : Run Last</programlisting>
 
442
<para>
 
443
 
 
444
</para><variablelist role="params">
 
445
<varlistentry><term><parameter>imcontext</parameter>&nbsp;:</term>
 
446
<listitem><simpara>the object which received the signal.
 
447
</simpara></listitem></varlistentry>
 
448
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
449
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
 
450
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
 
451
 
 
452
</simpara></listitem></varlistentry>
 
453
</variablelist></refsect2>
 
454
</refsect1>
 
455
 
 
456
 
 
457
 
 
458
</refentry>