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 	public static GType getType()
140 	{
141 		return gtk_im_context_get_type();
142 	}
143 
144 	/**
145 	 * Asks the widget that the input context is attached to to delete
146 	 * characters around the cursor position by emitting the
147 	 * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars
148 	 * are in characters not in bytes which differs from the usage other
149 	 * places in #GtkIMContext.
150 	 *
151 	 * In order to use this function, you should first call
152 	 * gtk_im_context_get_surrounding() to get the current context, and
153 	 * call this function immediately afterwards to make sure that you
154 	 * know what you are deleting. You should also account for the fact
155 	 * that even if the signal was handled, the input context might not
156 	 * have deleted all the characters that were requested to be deleted.
157 	 *
158 	 * This function is used by an input method that wants to make
159 	 * subsitutions in the existing text in response to new input. It is
160 	 * not useful for applications.
161 	 *
162 	 * Params:
163 	 *     offset = offset from cursor position in chars;
164 	 *         a negative value means start before the cursor.
165 	 *     nChars = number of characters to delete.
166 	 *
167 	 * Return: %TRUE if the signal was handled.
168 	 */
169 	public bool deleteSurrounding(int offset, int nChars)
170 	{
171 		return gtk_im_context_delete_surrounding(gtkIMContext, offset, nChars) != 0;
172 	}
173 
174 	/**
175 	 * Allow an input method to internally handle key press and release
176 	 * events. If this function returns %TRUE, then no further processing
177 	 * should be done for this key event.
178 	 *
179 	 * Params:
180 	 *     event = the key event
181 	 *
182 	 * Return: %TRUE if the input method handled the key event.
183 	 */
184 	public bool filterKeypress(GdkEventKey* event)
185 	{
186 		return gtk_im_context_filter_keypress(gtkIMContext, event) != 0;
187 	}
188 
189 	/**
190 	 * Notify the input method that the widget to which this
191 	 * input context corresponds has gained focus. The input method
192 	 * may, for example, change the displayed feedback to reflect
193 	 * this change.
194 	 */
195 	public void focusIn()
196 	{
197 		gtk_im_context_focus_in(gtkIMContext);
198 	}
199 
200 	/**
201 	 * Notify the input method that the widget to which this
202 	 * input context corresponds has lost focus. The input method
203 	 * may, for example, change the displayed feedback or reset the contexts
204 	 * state to reflect this change.
205 	 */
206 	public void focusOut()
207 	{
208 		gtk_im_context_focus_out(gtkIMContext);
209 	}
210 
211 	/**
212 	 * Retrieve the current preedit string for the input context,
213 	 * and a list of attributes to apply to the string.
214 	 * This string should be displayed inserted at the insertion
215 	 * point.
216 	 *
217 	 * Params:
218 	 *     str = location to store the retrieved
219 	 *         string. The string retrieved must be freed with g_free().
220 	 *     attrs = location to store the retrieved
221 	 *         attribute list.  When you are done with this list, you
222 	 *         must unreference it with pango_attr_list_unref().
223 	 *     cursorPos = location to store position of cursor (in characters)
224 	 *         within the preedit string.
225 	 */
226 	public void getPreeditString(out string str, out PgAttributeList attrs, out int cursorPos)
227 	{
228 		char* outstr = null;
229 		PangoAttrList* outattrs = null;
230 		
231 		gtk_im_context_get_preedit_string(gtkIMContext, &outstr, &outattrs, &cursorPos);
232 		
233 		str = Str.toString(outstr);
234 		attrs = ObjectG.getDObject!(PgAttributeList)(outattrs);
235 	}
236 
237 	/**
238 	 * Retrieves context around the insertion point. Input methods
239 	 * typically want context in order to constrain input text based on
240 	 * existing text; this is important for languages such as Thai where
241 	 * only some sequences of characters are allowed.
242 	 *
243 	 * This function is implemented by emitting the
244 	 * GtkIMContext::retrieve_surrounding signal on the input method; in
245 	 * response to this signal, a widget should provide as much context as
246 	 * is available, up to an entire paragraph, by calling
247 	 * gtk_im_context_set_surrounding(). Note that there is no obligation
248 	 * for a widget to respond to the ::retrieve_surrounding signal, so input
249 	 * methods must be prepared to function without context.
250 	 *
251 	 * Params:
252 	 *     text = location to store a UTF-8 encoded
253 	 *         string of text holding context around the insertion point.
254 	 *         If the function returns %TRUE, then you must free the result
255 	 *         stored in this location with g_free().
256 	 *     cursorIndex = location to store byte index of the insertion
257 	 *         cursor within @text.
258 	 *
259 	 * Return: %TRUE if surrounding text was provided; in this case
260 	 *     you must free the result stored in *text.
261 	 */
262 	public bool getSurrounding(out string text, out int cursorIndex)
263 	{
264 		char* outtext = null;
265 		
266 		auto p = gtk_im_context_get_surrounding(gtkIMContext, &outtext, &cursorIndex) != 0;
267 		
268 		text = Str.toString(outtext);
269 		
270 		return p;
271 	}
272 
273 	/**
274 	 * Notify the input method that a change such as a change in cursor
275 	 * position has been made. This will typically cause the input
276 	 * method to clear the preedit state.
277 	 */
278 	public void reset()
279 	{
280 		gtk_im_context_reset(gtkIMContext);
281 	}
282 
283 	/**
284 	 * Set the client window for the input context; this is the
285 	 * #GdkWindow in which the input appears. This window is
286 	 * used in order to correctly position status windows, and may
287 	 * also be used for purposes internal to the input method.
288 	 *
289 	 * Params:
290 	 *     window = the client window. This may be %NULL to indicate
291 	 *         that the previous client window no longer exists.
292 	 */
293 	public void setClientWindow(Window window)
294 	{
295 		gtk_im_context_set_client_window(gtkIMContext, (window is null) ? null : window.getWindowStruct());
296 	}
297 
298 	/**
299 	 * Notify the input method that a change in cursor
300 	 * position has been made. The location is relative to the client
301 	 * window.
302 	 *
303 	 * Params:
304 	 *     area = new location
305 	 */
306 	public void setCursorLocation(GdkRectangle* area)
307 	{
308 		gtk_im_context_set_cursor_location(gtkIMContext, area);
309 	}
310 
311 	/**
312 	 * Sets surrounding context around the insertion point and preedit
313 	 * string. This function is expected to be called in response to the
314 	 * GtkIMContext::retrieve_surrounding signal, and will likely have no
315 	 * effect if called at other times.
316 	 *
317 	 * Params:
318 	 *     text = text surrounding the insertion point, as UTF-8.
319 	 *         the preedit string should not be included within
320 	 *         @text.
321 	 *     len = the length of @text, or -1 if @text is nul-terminated
322 	 *     cursorIndex = the byte index of the insertion cursor within @text.
323 	 */
324 	public void setSurrounding(string text, int len, int cursorIndex)
325 	{
326 		gtk_im_context_set_surrounding(gtkIMContext, Str.toStringz(text), len, cursorIndex);
327 	}
328 
329 	/**
330 	 * Sets whether the IM context should use the preedit string
331 	 * to display feedback. If @use_preedit is FALSE (default
332 	 * is TRUE), then the IM context may use some other method to display
333 	 * feedback, such as displaying it in a child of the root window.
334 	 *
335 	 * Params:
336 	 *     usePreedit = whether the IM context should use the preedit string.
337 	 */
338 	public void setUsePreedit(bool usePreedit)
339 	{
340 		gtk_im_context_set_use_preedit(gtkIMContext, usePreedit);
341 	}
342 
343 	int[string] connectedSignals;
344 
345 	void delegate(string, IMContext)[] onCommitListeners;
346 	/**
347 	 * The ::commit signal is emitted when a complete input sequence
348 	 * has been entered by the user. This can be a single character
349 	 * immediately after a key press or the final result of preediting.
350 	 *
351 	 * Params:
352 	 *     str = the completed character(s) entered by the user
353 	 */
354 	void addOnCommit(void delegate(string, IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
355 	{
356 		if ( "commit" !in connectedSignals )
357 		{
358 			Signals.connectData(
359 				this,
360 				"commit",
361 				cast(GCallback)&callBackCommit,
362 				cast(void*)this,
363 				null,
364 				connectFlags);
365 			connectedSignals["commit"] = 1;
366 		}
367 		onCommitListeners ~= dlg;
368 	}
369 	extern(C) static void callBackCommit(GtkIMContext* imcontextStruct, char* str, IMContext _imcontext)
370 	{
371 		foreach ( void delegate(string, IMContext) dlg; _imcontext.onCommitListeners )
372 		{
373 			dlg(Str.toString(str), _imcontext);
374 		}
375 	}
376 
377 	bool delegate(int, int, IMContext)[] onDeleteSurroundingListeners;
378 	/**
379 	 * The ::delete-surrounding signal is emitted when the input method
380 	 * needs to delete all or part of the context surrounding the cursor.
381 	 *
382 	 * Params:
383 	 *     offset = the character offset from the cursor position of the text
384 	 *         to be deleted. A negative value indicates a position before
385 	 *         the cursor.
386 	 *     nChars = the number of characters to be deleted
387 	 *
388 	 * Return: %TRUE if the signal was handled.
389 	 */
390 	void addOnDeleteSurrounding(bool delegate(int, int, IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
391 	{
392 		if ( "delete-surrounding" !in connectedSignals )
393 		{
394 			Signals.connectData(
395 				this,
396 				"delete-surrounding",
397 				cast(GCallback)&callBackDeleteSurrounding,
398 				cast(void*)this,
399 				null,
400 				connectFlags);
401 			connectedSignals["delete-surrounding"] = 1;
402 		}
403 		onDeleteSurroundingListeners ~= dlg;
404 	}
405 	extern(C) static int callBackDeleteSurrounding(GtkIMContext* imcontextStruct, int offset, int nChars, IMContext _imcontext)
406 	{
407 		foreach ( bool delegate(int, int, IMContext) dlg; _imcontext.onDeleteSurroundingListeners )
408 		{
409 			if ( dlg(offset, nChars, _imcontext) )
410 			{
411 				return 1;
412 			}
413 		}
414 		
415 		return 0;
416 	}
417 
418 	void delegate(IMContext)[] onPreeditChangedListeners;
419 	/**
420 	 * The ::preedit-changed signal is emitted whenever the preedit sequence
421 	 * currently being entered has changed.  It is also emitted at the end of
422 	 * a preedit sequence, in which case
423 	 * gtk_im_context_get_preedit_string() returns the empty string.
424 	 */
425 	void addOnPreeditChanged(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
426 	{
427 		if ( "preedit-changed" !in connectedSignals )
428 		{
429 			Signals.connectData(
430 				this,
431 				"preedit-changed",
432 				cast(GCallback)&callBackPreeditChanged,
433 				cast(void*)this,
434 				null,
435 				connectFlags);
436 			connectedSignals["preedit-changed"] = 1;
437 		}
438 		onPreeditChangedListeners ~= dlg;
439 	}
440 	extern(C) static void callBackPreeditChanged(GtkIMContext* imcontextStruct, IMContext _imcontext)
441 	{
442 		foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditChangedListeners )
443 		{
444 			dlg(_imcontext);
445 		}
446 	}
447 
448 	void delegate(IMContext)[] onPreeditEndListeners;
449 	/**
450 	 * The ::preedit-end signal is emitted when a preediting sequence
451 	 * has been completed or canceled.
452 	 */
453 	void addOnPreeditEnd(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
454 	{
455 		if ( "preedit-end" !in connectedSignals )
456 		{
457 			Signals.connectData(
458 				this,
459 				"preedit-end",
460 				cast(GCallback)&callBackPreeditEnd,
461 				cast(void*)this,
462 				null,
463 				connectFlags);
464 			connectedSignals["preedit-end"] = 1;
465 		}
466 		onPreeditEndListeners ~= dlg;
467 	}
468 	extern(C) static void callBackPreeditEnd(GtkIMContext* imcontextStruct, IMContext _imcontext)
469 	{
470 		foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditEndListeners )
471 		{
472 			dlg(_imcontext);
473 		}
474 	}
475 
476 	void delegate(IMContext)[] onPreeditStartListeners;
477 	/**
478 	 * The ::preedit-start signal is emitted when a new preediting sequence
479 	 * starts.
480 	 */
481 	void addOnPreeditStart(void delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
482 	{
483 		if ( "preedit-start" !in connectedSignals )
484 		{
485 			Signals.connectData(
486 				this,
487 				"preedit-start",
488 				cast(GCallback)&callBackPreeditStart,
489 				cast(void*)this,
490 				null,
491 				connectFlags);
492 			connectedSignals["preedit-start"] = 1;
493 		}
494 		onPreeditStartListeners ~= dlg;
495 	}
496 	extern(C) static void callBackPreeditStart(GtkIMContext* imcontextStruct, IMContext _imcontext)
497 	{
498 		foreach ( void delegate(IMContext) dlg; _imcontext.onPreeditStartListeners )
499 		{
500 			dlg(_imcontext);
501 		}
502 	}
503 
504 	bool delegate(IMContext)[] onRetrieveSurroundingListeners;
505 	/**
506 	 * The ::retrieve-surrounding signal is emitted when the input method
507 	 * requires the context surrounding the cursor.  The callback should set
508 	 * the input method surrounding context by calling the
509 	 * gtk_im_context_set_surrounding() method.
510 	 *
511 	 * Return: %TRUE if the signal was handled.
512 	 */
513 	void addOnRetrieveSurrounding(bool delegate(IMContext) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
514 	{
515 		if ( "retrieve-surrounding" !in connectedSignals )
516 		{
517 			Signals.connectData(
518 				this,
519 				"retrieve-surrounding",
520 				cast(GCallback)&callBackRetrieveSurrounding,
521 				cast(void*)this,
522 				null,
523 				connectFlags);
524 			connectedSignals["retrieve-surrounding"] = 1;
525 		}
526 		onRetrieveSurroundingListeners ~= dlg;
527 	}
528 	extern(C) static int callBackRetrieveSurrounding(GtkIMContext* imcontextStruct, IMContext _imcontext)
529 	{
530 		foreach ( bool delegate(IMContext) dlg; _imcontext.onRetrieveSurroundingListeners )
531 		{
532 			if ( dlg(_imcontext) )
533 			{
534 				return 1;
535 			}
536 		}
537 		
538 		return 0;
539 	}
540 }