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