1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.IMContext; 26 27 private import gdk.Window; 28 private import glib.Str; 29 private import gobject.ObjectG; 30 private import gobject.Signals; 31 public import gtkc.gdktypes; 32 private import gtkc.gtk; 33 public import gtkc.gtktypes; 34 private import pango.PgAttributeList; 35 36 37 /** 38 * #GtkIMContext defines the interface for GTK+ input methods. An input method 39 * is used by GTK+ text input widgets like #GtkEntry to map from key events to 40 * Unicode character strings. 41 * 42 * The default input method can be set programmatically via the 43 * #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set 44 * the GTK_IM_MODULE environment variable as documented in 45 * [Running GTK+ Applications][gtk-running]. 46 * 47 * The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module 48 * properties may also be used to set input methods for specific widget 49 * instances. For instance, a certain entry widget might be expected to contain 50 * certain characters which would be easier to input with a certain input 51 * method. 52 * 53 * An input method may consume multiple key events in sequence and finally 54 * output the composed result. This is called preediting, and an input method 55 * may provide feedback about this process by displaying the intermediate 56 * composition states as preedit text. For instance, the default GTK+ input 57 * method implements the input of arbitrary Unicode code points by holding down 58 * the Control and Shift keys and then typing “U” followed by the hexadecimal 59 * digits of the code point. When releasing the Control and Shift keys, 60 * preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for 61 * example results in the € sign. 62 * 63 * Additional input methods can be made available for use by GTK+ widgets as 64 * loadable modules. An input method module is a small shared library which 65 * implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports 66 * these four functions: 67 * 68 * |[<!-- language="C" --> 69 * void im_module_init(#GTypeModule *module); 70 * ]| 71 * This function should register the #GType of the #GtkIMContext subclass which 72 * implements the input method by means of g_type_module_register_type(). Note 73 * that g_type_register_static() cannot be used as the type needs to be 74 * registered dynamically. 75 * 76 * |[<!-- language="C" --> 77 * void im_module_exit(void); 78 * ]| 79 * Here goes any cleanup code your input method might require on module unload. 80 * 81 * |[<!-- language="C" --> 82 * void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts) 83 * { 84 * *contexts = info_list; 85 * *n_contexts = G_N_ELEMENTS (info_list); 86 * } 87 * ]| 88 * This function returns the list of input methods provided by the module. The 89 * example implementation above shows a common solution and simply returns a 90 * pointer to statically defined array of #GtkIMContextInfo items for each 91 * provided input method. 92 * 93 * |[<!-- language="C" --> 94 * #GtkIMContext * im_module_create(const #gchar *context_id); 95 * ]| 96 * This function should return a pointer to a newly created instance of the 97 * #GtkIMContext subclass identified by @context_id. The context ID is the same 98 * as specified in the #GtkIMContextInfo array returned by im_module_list(). 99 * 100 * After a new loadable input method module has been installed on the system, 101 * the configuration file `gtk.immodules` needs to be 102 * regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0], 103 * in order for the new input method to become available to GTK+ applications. 104 */ 105 public class IMContext : ObjectG 106 { 107 /** the main Gtk struct */ 108 protected GtkIMContext* gtkIMContext; 109 110 /** Get the main Gtk struct */ 111 public GtkIMContext* getIMContextStruct() 112 { 113 return gtkIMContext; 114 } 115 116 /** the main Gtk struct as a void* */ 117 protected override void* getStruct() 118 { 119 return cast(void*)gtkIMContext; 120 } 121 122 protected override void setStruct(GObject* obj) 123 { 124 gtkIMContext = cast(GtkIMContext*)obj; 125 super.setStruct(obj); 126 } 127 128 /** 129 * Sets our main struct and passes it to the parent class. 130 */ 131 public this (GtkIMContext* gtkIMContext, bool ownedRef = false) 132 { 133 this.gtkIMContext = gtkIMContext; 134 super(cast(GObject*)gtkIMContext, ownedRef); 135 } 136 137 /** 138 */ 139 140 public static GType getType() 141 { 142 return gtk_im_context_get_type(); 143 } 144 145 /** 146 * Asks the widget that the input context is attached to to delete 147 * characters around the cursor position by emitting the 148 * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars 149 * are in characters not in bytes which differs from the usage other 150 * places in #GtkIMContext. 151 * 152 * In order to use this function, you should first call 153 * gtk_im_context_get_surrounding() to get the current context, and 154 * call this function immediately afterwards to make sure that you 155 * know what you are deleting. You should also account for the fact 156 * that even if the signal was handled, the input context might not 157 * have deleted all the characters that were requested to be deleted. 158 * 159 * This function is used by an input method that wants to make 160 * subsitutions in the existing text in response to new input. It is 161 * not useful for applications. 162 * 163 * Params: 164 * offset = offset from cursor position in chars; 165 * a negative value means start before the cursor. 166 * nChars = number of characters to delete. 167 * 168 * Return: %TRUE if the signal was handled. 169 */ 170 public bool deleteSurrounding(int offset, int nChars) 171 { 172 return gtk_im_context_delete_surrounding(gtkIMContext, offset, nChars) != 0; 173 } 174 175 /** 176 * Allow an input method to internally handle key press and release 177 * events. If this function returns %TRUE, then no further processing 178 * should be done for this key event. 179 * 180 * Params: 181 * event = the key event 182 * 183 * Return: %TRUE if the input method handled the key event. 184 */ 185 public bool filterKeypress(GdkEventKey* event) 186 { 187 return gtk_im_context_filter_keypress(gtkIMContext, event) != 0; 188 } 189 190 /** 191 * Notify the input method that the widget to which this 192 * input context corresponds has gained focus. The input method 193 * may, for example, change the displayed feedback to reflect 194 * this change. 195 */ 196 public void focusIn() 197 { 198 gtk_im_context_focus_in(gtkIMContext); 199 } 200 201 /** 202 * Notify the input method that the widget to which this 203 * input context corresponds has lost focus. The input method 204 * may, for example, change the displayed feedback or reset the contexts 205 * state to reflect this change. 206 */ 207 public void focusOut() 208 { 209 gtk_im_context_focus_out(gtkIMContext); 210 } 211 212 /** 213 * Retrieve the current preedit string for the input context, 214 * and a list of attributes to apply to the string. 215 * This string should be displayed inserted at the insertion 216 * point. 217 * 218 * Params: 219 * str = location to store the retrieved 220 * string. The string retrieved must be freed with g_free(). 221 * attrs = location to store the retrieved 222 * attribute list. When you are done with this list, you 223 * must unreference it with pango_attr_list_unref(). 224 * cursorPos = location to store position of cursor (in characters) 225 * within the preedit string. 226 */ 227 public void getPreeditString(out string str, out PgAttributeList attrs, out int cursorPos) 228 { 229 char* outstr = null; 230 PangoAttrList* outattrs = null; 231 232 gtk_im_context_get_preedit_string(gtkIMContext, &outstr, &outattrs, &cursorPos); 233 234 str = Str.toString(outstr); 235 attrs = ObjectG.getDObject!(PgAttributeList)(outattrs); 236 } 237 238 /** 239 * Retrieves context around the insertion point. Input methods 240 * typically want context in order to constrain input text based on 241 * existing text; this is important for languages such as Thai where 242 * only some sequences of characters are allowed. 243 * 244 * This function is implemented by emitting the 245 * GtkIMContext::retrieve_surrounding signal on the input method; in 246 * response to this signal, a widget should provide as much context as 247 * is available, up to an entire paragraph, by calling 248 * gtk_im_context_set_surrounding(). Note that there is no obligation 249 * for a widget to respond to the ::retrieve_surrounding signal, so input 250 * methods must be prepared to function without context. 251 * 252 * Params: 253 * text = location to store a UTF-8 encoded 254 * string of text holding context around the insertion point. 255 * If the function returns %TRUE, then you must free the result 256 * stored in this location with g_free(). 257 * cursorIndex = location to store byte index of the insertion 258 * cursor within @text. 259 * 260 * Return: %TRUE if surrounding text was provided; in this case 261 * you must free the result stored in *text. 262 */ 263 public bool getSurrounding(out string text, out int cursorIndex) 264 { 265 char* outtext = null; 266 267 auto p = gtk_im_context_get_surrounding(gtkIMContext, &outtext, &cursorIndex) != 0; 268 269 text = Str.toString(outtext); 270 271 return p; 272 } 273 274 /** 275 * Notify the input method that a change such as a change in cursor 276 * position has been made. This will typically cause the input 277 * method to clear the preedit state. 278 */ 279 public void reset() 280 { 281 gtk_im_context_reset(gtkIMContext); 282 } 283 284 /** 285 * Set the client window for the input context; this is the 286 * #GdkWindow in which the input appears. This window is 287 * used in order to correctly position status windows, and may 288 * also be used for purposes internal to the input method. 289 * 290 * Params: 291 * window = the client window. This may be %NULL to indicate 292 * that the previous client window no longer exists. 293 */ 294 public void setClientWindow(Window window) 295 { 296 gtk_im_context_set_client_window(gtkIMContext, (window is null) ? null : window.getWindowStruct()); 297 } 298 299 /** 300 * Notify the input method that a change in cursor 301 * position has been made. The location is relative to the client 302 * window. 303 * 304 * Params: 305 * area = new location 306 */ 307 public void setCursorLocation(GdkRectangle* area) 308 { 309 gtk_im_context_set_cursor_location(gtkIMContext, area); 310 } 311 312 /** 313 * Sets surrounding context around the insertion point and preedit 314 * string. This function is expected to be called in response to the 315 * GtkIMContext::retrieve_surrounding signal, and will likely have no 316 * effect if called at other times. 317 * 318 * Params: 319 * text = text surrounding the insertion point, as UTF-8. 320 * the preedit string should not be included within 321 * @text. 322 * len = the length of @text, or -1 if @text is nul-terminated 323 * cursorIndex = the byte index of the insertion cursor within @text. 324 */ 325 public void setSurrounding(string text, int len, int cursorIndex) 326 { 327 gtk_im_context_set_surrounding(gtkIMContext, Str.toStringz(text), len, cursorIndex); 328 } 329 330 /** 331 * Sets whether the IM context should use the preedit string 332 * to display feedback. If @use_preedit is FALSE (default 333 * is TRUE), then the IM context may use some other method to display 334 * feedback, such as displaying it in a child of the root window. 335 * 336 * Params: 337 * usePreedit = whether the IM context should use the preedit string. 338 */ 339 public void setUsePreedit(bool usePreedit) 340 { 341 gtk_im_context_set_use_preedit(gtkIMContext, usePreedit); 342 } 343 344 int[string] connectedSignals; 345 346 void delegate(string, IMContext)[] onCommitListeners; 347 /** 348 * The ::commit signal is emitted when a complete input sequence 349 * has been entered by the user. This can be a single character 350 * immediately after a key press or the final result of preediting. 351 * 352 * Params: 353 * str = the completed character(s) entered by the user 354 */ 355 void addOnCommit(void delegate(string, IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 356 { 357 if ( "commit" !in connectedSignals ) 358 { 359 Signals.connectData( 360 this, 361 "commit", 362 cast(GCallback)&callBackCommit, 363 cast(void*)this, 364 null, 365 connectFlags); 366 connectedSignals["commit"] = 1; 367 } 368 onCommitListeners ~= dlg; 369 } 370 extern(C) static void callBackCommit(GtkIMContext* imcontextStruct, char* str, IMContext _imcontext) 371 { 372 foreach ( void delegate(string, IMContext) dlg; _imcontext.onCommitListeners ) 373 { 374 dlg(Str.toString(str), _imcontext); 375 } 376 } 377 378 bool delegate(int, int, IMContext)[] onDeleteSurroundingListeners; 379 /** 380 * The ::delete-surrounding signal is emitted when the input method 381 * needs to delete all or part of the context surrounding the cursor. 382 * 383 * Params: 384 * offset = the character offset from the cursor position of the text 385 * to be deleted. A negative value indicates a position before 386 * the cursor. 387 * nChars = the number of characters to be deleted 388 * 389 * Return: %TRUE if the signal was handled. 390 */ 391 void addOnDeleteSurrounding(bool delegate(int, int, IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 392 { 393 if ( "delete-surrounding" !in connectedSignals ) 394 { 395 Signals.connectData( 396 this, 397 "delete-surrounding", 398 cast(GCallback)&callBackDeleteSurrounding, 399 cast(void*)this, 400 null, 401 connectFlags); 402 connectedSignals["delete-surrounding"] = 1; 403 } 404 onDeleteSurroundingListeners ~= dlg; 405 } 406 extern(C) static int callBackDeleteSurrounding(GtkIMContext* imcontextStruct, int offset, int nChars, IMContext _imcontext) 407 { 408 foreach ( bool delegate(int, int, IMContext) dlg; _imcontext.onDeleteSurroundingListeners ) 409 { 410 if ( dlg(offset, nChars, _imcontext) ) 411 { 412 return 1; 413 } 414 } 415 416 return 0; 417 } 418 419 void delegate(IMContext)[] onPreeditChangedListeners; 420 /** 421 * The ::preedit-changed signal is emitted whenever the preedit sequence 422 * currently being entered has changed. It is also emitted at the end of 423 * a preedit sequence, in which case 424 * gtk_im_context_get_preedit_string() returns the empty string. 425 */ 426 void addOnPreeditChanged(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 427 { 428 if ( "preedit-changed" !in connectedSignals ) 429 { 430 Signals.connectData( 431 this, 432 "preedit-changed", 433 cast(GCallback)&callBackPreeditChanged, 434 cast(void*)this, 435 null, 436 connectFlags); 437 connectedSignals["preedit-changed"] = 1; 438 } 439 onPreeditChangedListeners ~= dlg; 440 } 441 extern(C) static void callBackPreeditChanged(GtkIMContext* imcontextStruct, IMContext _imcontext) 442 { 443 foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditChangedListeners ) 444 { 445 dlg(_imcontext); 446 } 447 } 448 449 void delegate(IMContext)[] onPreeditEndListeners; 450 /** 451 * The ::preedit-end signal is emitted when a preediting sequence 452 * has been completed or canceled. 453 */ 454 void addOnPreeditEnd(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 455 { 456 if ( "preedit-end" !in connectedSignals ) 457 { 458 Signals.connectData( 459 this, 460 "preedit-end", 461 cast(GCallback)&callBackPreeditEnd, 462 cast(void*)this, 463 null, 464 connectFlags); 465 connectedSignals["preedit-end"] = 1; 466 } 467 onPreeditEndListeners ~= dlg; 468 } 469 extern(C) static void callBackPreeditEnd(GtkIMContext* imcontextStruct, IMContext _imcontext) 470 { 471 foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditEndListeners ) 472 { 473 dlg(_imcontext); 474 } 475 } 476 477 void delegate(IMContext)[] onPreeditStartListeners; 478 /** 479 * The ::preedit-start signal is emitted when a new preediting sequence 480 * starts. 481 */ 482 void addOnPreeditStart(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 483 { 484 if ( "preedit-start" !in connectedSignals ) 485 { 486 Signals.connectData( 487 this, 488 "preedit-start", 489 cast(GCallback)&callBackPreeditStart, 490 cast(void*)this, 491 null, 492 connectFlags); 493 connectedSignals["preedit-start"] = 1; 494 } 495 onPreeditStartListeners ~= dlg; 496 } 497 extern(C) static void callBackPreeditStart(GtkIMContext* imcontextStruct, IMContext _imcontext) 498 { 499 foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditStartListeners ) 500 { 501 dlg(_imcontext); 502 } 503 } 504 505 bool delegate(IMContext)[] onRetrieveSurroundingListeners; 506 /** 507 * The ::retrieve-surrounding signal is emitted when the input method 508 * requires the context surrounding the cursor. The callback should set 509 * the input method surrounding context by calling the 510 * gtk_im_context_set_surrounding() method. 511 * 512 * Return: %TRUE if the signal was handled. 513 */ 514 void addOnRetrieveSurrounding(bool delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 515 { 516 if ( "retrieve-surrounding" !in connectedSignals ) 517 { 518 Signals.connectData( 519 this, 520 "retrieve-surrounding", 521 cast(GCallback)&callBackRetrieveSurrounding, 522 cast(void*)this, 523 null, 524 connectFlags); 525 connectedSignals["retrieve-surrounding"] = 1; 526 } 527 onRetrieveSurroundingListeners ~= dlg; 528 } 529 extern(C) static int callBackRetrieveSurrounding(GtkIMContext* imcontextStruct, IMContext _imcontext) 530 { 531 foreach ( bool delegate(IMContext) dlg; _imcontext.onRetrieveSurroundingListeners ) 532 { 533 if ( dlg(_imcontext) ) 534 { 535 return 1; 536 } 537 } 538 539 return 0; 540 } 541 }