1
2@c %start of fragment
3
4@deftp Class <gtk-im-context>
5Derives from @code{<gobject>}.
6
7This class defines no direct slots.
8
9@end deftp
10
11@defop Signal <gtk-im-context> preedit-start
12@end defop
13
14@defop Signal <gtk-im-context> preedit-end
15@end defop
16
17@defop Signal <gtk-im-context> preedit-changed
18@end defop
19
20@defop Signal <gtk-im-context> commit  (arg0@tie{}@code{<gchararray>})
21@end defop
22
23@defop Signal <gtk-im-context> retrieve-surrounding  @result{}@tie{}@code{<gboolean>}
24@end defop
25
26@defop Signal <gtk-im-context> delete-surrounding  (arg0@tie{}@code{<gint>}) (arg1@tie{}@code{<gint>}) @result{}@tie{}@code{<gboolean>}
27@end defop
28
29@deffn Function gtk-im-context-set-client-window  (self@tie{}@code{<gtk-im-context>}) (window@tie{}@code{<gdk-window>})
30@deffnx Method set-client-window
31Set the client window for the input context; this is the @code{<gdk-window>} in
32which the input appears. This window is used in order to correctly position
33status windows, and may also be used for purposes internal to the input method.
34
35@table @var
36@item context
37a @code{<gtk-im-context>}
38
39@item window
40the client window. This may be @samp{@code{#f}} to indicate that the previous
41client window no longer exists.
42
43@end table
44
45@end deffn
46
47@deffn Function gtk-im-context-filter-keypress  (self@tie{}@code{<gtk-im-context>}) (event@tie{}@code{<gdk-event-key>}) @result{}@tie{} (ret@tie{}@code{bool})
48@deffnx Method filter-keypress
49Allow an input method to internally handle key press and release events. If this
50function returns @samp{@code{#t}}, then no further processing should be done for
51this key event.
52
53@table @var
54@item context
55a @code{<gtk-im-context>}
56
57@item event
58the key event
59
60@item ret
61@samp{@code{#t}} if the input method handled the key event.
62
63@end table
64
65@end deffn
66
67@deffn Function gtk-im-context-focus-in  (self@tie{}@code{<gtk-im-context>})
68@deffnx Method focus-in
69Notify the input method that the widget to which this input context corresponds
70has gained focus. The input method may, for example, change the displayed
71feedback to reflect this change.
72
73@table @var
74@item context
75a @code{<gtk-im-context>}
76
77@end table
78
79@end deffn
80
81@deffn Function gtk-im-context-focus-out  (self@tie{}@code{<gtk-im-context>})
82@deffnx Method focus-out
83Notify the input method that the widget to which this input context corresponds
84has lost focus. The input method may, for example, change the displayed feedback
85or reset the contexts state to reflect this change.
86
87@table @var
88@item context
89a @code{<gtk-im-context>}
90
91@end table
92
93@end deffn
94
95@deffn Function gtk-im-context-reset  (self@tie{}@code{<gtk-im-context>})
96@deffnx Method reset
97Notify the input method that a change such as a change in cursor position has
98been made. This will typically cause the input method to clear the preedit
99state.
100
101@table @var
102@item context
103a @code{<gtk-im-context>}
104
105@end table
106
107@end deffn
108
109@deffn Function gtk-im-context-set-cursor-location  (self@tie{}@code{<gtk-im-context>}) (area@tie{}@code{<gdk-rectangle>})
110@deffnx Method set-cursor-location
111Notify the input method that a change in cursor position has been made. The
112location is relative to the client window.
113
114@table @var
115@item context
116a @code{<gtk-im-context>}
117
118@item area
119new location
120
121@end table
122
123@end deffn
124
125@deffn Function gtk-im-context-set-use-preedit  (self@tie{}@code{<gtk-im-context>}) (use_preedit@tie{}@code{bool})
126@deffnx Method set-use-preedit
127Sets whether the IM context should use the preedit string to display feedback.
128If @var{use-preedit} is FALSE (default is TRUE), then the IM context may use
129some other method to display feedback, such as displaying it in a child of the
130root window.
131
132@table @var
133@item context
134a @code{<gtk-im-context>}
135
136@item use-preedit
137whether the IM context should use the preedit string.
138
139@end table
140
141@end deffn
142
143@deffn Function gtk-im-context-set-surrounding  (self@tie{}@code{<gtk-im-context>}) (text@tie{}@code{mchars}) (len@tie{}@code{int}) (cursor_index@tie{}@code{int})
144@deffnx Method set-surrounding
145Sets surrounding context around the insertion point and preedit string. This
146function is expected to be called in response to the
147GtkIMContext::retrieve_surrounding signal, and will likely have no effect if
148called at other times.
149
150@table @var
151@item context
152a @code{<gtk-im-context>}
153
154@item text
155text surrounding the insertion point, as UTF-8. the preedit string should not be
156included within @var{text}.
157
158@item len
159the length of @var{text}, or -1 if @var{text} is nul-terminated
160
161@item cursor-index
162the byte index of the insertion cursor within @var{text}.
163
164@end table
165
166@end deffn
167
168@deffn Function gtk-im-context-get-surrounding  (self@tie{}@code{<gtk-im-context>}) @result{}@tie{} (ret@tie{}@code{bool}) (text@tie{}@code{mchars}) (cursor_index@tie{}@code{int})
169@deffnx Method get-surrounding
170Retrieves context around the insertion point. Input methods typically want
171context in order to constrain input text based on existing text; this is
172important for languages such as Thai where only some sequences of characters are
173allowed.
174
175This function is implemented by emitting the GtkIMContext::retrieve_surrounding
176signal on the input method; in response to this signal, a widget should provide
177as much context as is available, up to an entire paragraph, by calling
178@code{gtk-im-context-set-surrounding}. Note that there is no obligation for a
179widget to respond to the ::retrieve_surrounding signal, so input methods must be
180prepared to function without context.
181
182@table @var
183@item context
184a @code{<gtk-im-context>}
185
186@item text
187location to store a UTF-8 encoded string of text holding context around the
188insertion point. If the function returns @samp{@code{#t}}, then you must free
189the result stored in this location with @code{g-free}.
190
191@item cursor-index
192location to store byte index of the insertion cursor within @var{text}.
193
194@item ret
195@samp{@code{#t}} if surrounding text was provided; in this case you must free
196the result stored in *text.
197
198@end table
199
200@end deffn
201
202@deffn Function gtk-im-context-delete-surrounding  (self@tie{}@code{<gtk-im-context>}) (offset@tie{}@code{int}) (n_chars@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{bool})
203@deffnx Method delete-surrounding
204Asks the widget that the input context is attached to to delete characters
205around the cursor position by emitting the GtkIMContext::delete_surrounding
206signal. Note that @var{offset} and @var{n-chars} are in characters not in bytes
207which differs from the usage other places in @code{<gtk-im-context>}.
208
209In order to use this function, you should first call
210@code{gtk-im-context-get-surrounding} to get the current context, and call this
211function immediately afterwards to make sure that you know what you are
212deleting. You should also account for the fact that even if the signal was
213handled, the input context might not have deleted all the characters that were
214requested to be deleted.
215
216This function is used by an input method that wants to make subsitutions in the
217existing text in response to new input. It is not useful for applications.
218
219@table @var
220@item context
221a @code{<gtk-im-context>}
222
223@item offset
224offset from cursor position in chars; a negative value means start before the
225cursor.
226
227@item n-chars
228number of characters to delete.
229
230@item ret
231@samp{@code{#t}} if the signal was handled.
232
233@end table
234
235@end deffn
236
237
238@c %end of fragment
239