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 gdk.Keymap;
26 
27 private import gdk.Display;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gtkc.gdk;
32 public  import gtkc.gdktypes;
33 
34 
35 /**
36  * A #GdkKeymap defines the translation from keyboard state
37  * (including a hardware key, a modifier mask, and active keyboard group)
38  * to a keyval. This translation has two phases. The first phase is
39  * to determine the effective keyboard group and level for the keyboard
40  * state; the second phase is to look up the keycode/group/level triplet
41  * in the keymap and see what keyval it corresponds to.
42  */
43 public class Keymap : ObjectG
44 {
45 	/** the main Gtk struct */
46 	protected GdkKeymap* gdkKeymap;
47 
48 	/** Get the main Gtk struct */
49 	public GdkKeymap* getKeymapStruct()
50 	{
51 		return gdkKeymap;
52 	}
53 
54 	/** the main Gtk struct as a void* */
55 	protected override void* getStruct()
56 	{
57 		return cast(void*)gdkKeymap;
58 	}
59 
60 	protected override void setStruct(GObject* obj)
61 	{
62 		gdkKeymap = cast(GdkKeymap*)obj;
63 		super.setStruct(obj);
64 	}
65 
66 	/**
67 	 * Sets our main struct and passes it to the parent class.
68 	 */
69 	public this (GdkKeymap* gdkKeymap, bool ownedRef = false)
70 	{
71 		this.gdkKeymap = gdkKeymap;
72 		super(cast(GObject*)gdkKeymap, ownedRef);
73 	}
74 
75 
76 	/** */
77 	public static GType getType()
78 	{
79 		return gdk_keymap_get_type();
80 	}
81 
82 	/**
83 	 * Returns the #GdkKeymap attached to the default display.
84 	 *
85 	 * Return: the #GdkKeymap attached to the default display.
86 	 */
87 	public static Keymap getDefault()
88 	{
89 		auto p = gdk_keymap_get_default();
90 		
91 		if(p is null)
92 		{
93 			return null;
94 		}
95 		
96 		return ObjectG.getDObject!(Keymap)(cast(GdkKeymap*) p);
97 	}
98 
99 	/**
100 	 * Returns the #GdkKeymap attached to @display.
101 	 *
102 	 * Params:
103 	 *     display = the #GdkDisplay.
104 	 *
105 	 * Return: the #GdkKeymap attached to @display.
106 	 *
107 	 * Since: 2.2
108 	 */
109 	public static Keymap getForDisplay(Display display)
110 	{
111 		auto p = gdk_keymap_get_for_display((display is null) ? null : display.getDisplayStruct());
112 		
113 		if(p is null)
114 		{
115 			return null;
116 		}
117 		
118 		return ObjectG.getDObject!(Keymap)(cast(GdkKeymap*) p);
119 	}
120 
121 	/**
122 	 * Maps the non-virtual modifiers (i.e Mod2, Mod3, ...) which are set
123 	 * in @state to the virtual modifiers (i.e. Super, Hyper and Meta) and
124 	 * set the corresponding bits in @state.
125 	 *
126 	 * GDK already does this before delivering key events, but for
127 	 * compatibility reasons, it only sets the first virtual modifier
128 	 * it finds, whereas this function sets all matching virtual modifiers.
129 	 *
130 	 * This function is useful when matching key events against
131 	 * accelerators.
132 	 *
133 	 * Params:
134 	 *     state = pointer to the modifier mask to change
135 	 *
136 	 * Since: 2.20
137 	 */
138 	public void addVirtualModifiers(ref GdkModifierType state)
139 	{
140 		gdk_keymap_add_virtual_modifiers(gdkKeymap, &state);
141 	}
142 
143 	/**
144 	 * Returns whether the Caps Lock modifer is locked.
145 	 *
146 	 * Return: %TRUE if Caps Lock is on
147 	 *
148 	 * Since: 2.16
149 	 */
150 	public bool getCapsLockState()
151 	{
152 		return gdk_keymap_get_caps_lock_state(gdkKeymap) != 0;
153 	}
154 
155 	/**
156 	 * Returns the direction of effective layout of the keymap.
157 	 *
158 	 * Return: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
159 	 *     if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
160 	 *     otherwise.
161 	 */
162 	public PangoDirection getDirection()
163 	{
164 		return gdk_keymap_get_direction(gdkKeymap);
165 	}
166 
167 	/**
168 	 * Returns the keyvals bound to @hardware_keycode.
169 	 * The Nth #GdkKeymapKey in @keys is bound to the Nth
170 	 * keyval in @keyvals. Free the returned arrays with g_free().
171 	 * When a keycode is pressed by the user, the keyval from
172 	 * this list of entries is selected by considering the effective
173 	 * keyboard group and level. See gdk_keymap_translate_keyboard_state().
174 	 *
175 	 * Params:
176 	 *     hardwareKeycode = a keycode
177 	 *     keys = return
178 	 *         location for array of #GdkKeymapKey, or %NULL
179 	 *     keyvals = return
180 	 *         location for array of keyvals, or %NULL
181 	 *     nEntries = length of @keys and @keyvals
182 	 *
183 	 * Return: %TRUE if there were any entries
184 	 */
185 	public bool getEntriesForKeycode(uint hardwareKeycode, out GdkKeymapKey[] keys, out uint[] keyvals)
186 	{
187 		GdkKeymapKey* outkeys = null;
188 		uint* outkeyvals = null;
189 		int nEntries;
190 		
191 		auto p = gdk_keymap_get_entries_for_keycode(gdkKeymap, hardwareKeycode, &outkeys, &outkeyvals, &nEntries) != 0;
192 		
193 		keys = outkeys[0 .. nEntries];
194 		keyvals = outkeyvals[0 .. nEntries];
195 		
196 		return p;
197 	}
198 
199 	/**
200 	 * Obtains a list of keycode/group/level combinations that will
201 	 * generate @keyval. Groups and levels are two kinds of keyboard mode;
202 	 * in general, the level determines whether the top or bottom symbol
203 	 * on a key is used, and the group determines whether the left or
204 	 * right symbol is used. On US keyboards, the shift key changes the
205 	 * keyboard level, and there are no groups. A group switch key might
206 	 * convert a keyboard between Hebrew to English modes, for example.
207 	 * #GdkEventKey contains a %group field that indicates the active
208 	 * keyboard group. The level is computed from the modifier mask.
209 	 * The returned array should be freed
210 	 * with g_free().
211 	 *
212 	 * Params:
213 	 *     keyval = a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
214 	 *     keys = return location
215 	 *         for an array of #GdkKeymapKey
216 	 *     nKeys = return location for number of elements in returned array
217 	 *
218 	 * Return: %TRUE if keys were found and returned
219 	 */
220 	public bool getEntriesForKeyval(uint keyval, out GdkKeymapKey[] keys)
221 	{
222 		GdkKeymapKey* outkeys = null;
223 		int nKeys;
224 		
225 		auto p = gdk_keymap_get_entries_for_keyval(gdkKeymap, keyval, &outkeys, &nKeys) != 0;
226 		
227 		keys = outkeys[0 .. nKeys];
228 		
229 		return p;
230 	}
231 
232 	/**
233 	 * Returns the modifier mask the @keymap’s windowing system backend
234 	 * uses for a particular purpose.
235 	 *
236 	 * Note that this function always returns real hardware modifiers, not
237 	 * virtual ones (e.g. it will return #GDK_MOD1_MASK rather than
238 	 * #GDK_META_MASK if the backend maps MOD1 to META), so there are use
239 	 * cases where the return value of this function has to be transformed
240 	 * by gdk_keymap_add_virtual_modifiers() in order to contain the
241 	 * expected result.
242 	 *
243 	 * Params:
244 	 *     intent = the use case for the modifier mask
245 	 *
246 	 * Return: the modifier mask used for @intent.
247 	 *
248 	 * Since: 3.4
249 	 */
250 	public GdkModifierType getModifierMask(GdkModifierIntent intent)
251 	{
252 		return gdk_keymap_get_modifier_mask(gdkKeymap, intent);
253 	}
254 
255 	/**
256 	 * Returns the current modifier state.
257 	 *
258 	 * Return: the current modifier state.
259 	 *
260 	 * Since: 3.4
261 	 */
262 	public uint getModifierState()
263 	{
264 		return gdk_keymap_get_modifier_state(gdkKeymap);
265 	}
266 
267 	/**
268 	 * Returns whether the Num Lock modifer is locked.
269 	 *
270 	 * Return: %TRUE if Num Lock is on
271 	 *
272 	 * Since: 3.0
273 	 */
274 	public bool getNumLockState()
275 	{
276 		return gdk_keymap_get_num_lock_state(gdkKeymap) != 0;
277 	}
278 
279 	/**
280 	 * Returns whether the Scroll Lock modifer is locked.
281 	 *
282 	 * Return: %TRUE if Scroll Lock is on
283 	 *
284 	 * Since: 3.18
285 	 */
286 	public bool getScrollLockState()
287 	{
288 		return gdk_keymap_get_scroll_lock_state(gdkKeymap) != 0;
289 	}
290 
291 	/**
292 	 * Determines if keyboard layouts for both right-to-left and left-to-right
293 	 * languages are in use.
294 	 *
295 	 * Return: %TRUE if there are layouts in both directions, %FALSE otherwise
296 	 *
297 	 * Since: 2.12
298 	 */
299 	public bool haveBidiLayouts()
300 	{
301 		return gdk_keymap_have_bidi_layouts(gdkKeymap) != 0;
302 	}
303 
304 	/**
305 	 * Looks up the keyval mapped to a keycode/group/level triplet.
306 	 * If no keyval is bound to @key, returns 0. For normal user input,
307 	 * you want to use gdk_keymap_translate_keyboard_state() instead of
308 	 * this function, since the effective group/level may not be
309 	 * the same as the current keyboard state.
310 	 *
311 	 * Params:
312 	 *     key = a #GdkKeymapKey with keycode, group, and level initialized
313 	 *
314 	 * Return: a keyval, or 0 if none was mapped to the given @key
315 	 */
316 	public uint lookupKey(GdkKeymapKey* key)
317 	{
318 		return gdk_keymap_lookup_key(gdkKeymap, key);
319 	}
320 
321 	/**
322 	 * Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
323 	 * are set in @state to their non-virtual counterparts (i.e. Mod2,
324 	 * Mod3,...) and set the corresponding bits in @state.
325 	 *
326 	 * This function is useful when matching key events against
327 	 * accelerators.
328 	 *
329 	 * Params:
330 	 *     state = pointer to the modifier state to map
331 	 *
332 	 * Return: %FALSE if two virtual modifiers were mapped to the
333 	 *     same non-virtual modifier. Note that %FALSE is also returned
334 	 *     if a virtual modifier is mapped to a non-virtual modifier that
335 	 *     was already set in @state.
336 	 *
337 	 * Since: 2.20
338 	 */
339 	public bool mapVirtualModifiers(ref GdkModifierType state)
340 	{
341 		return gdk_keymap_map_virtual_modifiers(gdkKeymap, &state) != 0;
342 	}
343 
344 	/**
345 	 * Translates the contents of a #GdkEventKey into a keyval, effective
346 	 * group, and level. Modifiers that affected the translation and
347 	 * are thus unavailable for application use are returned in
348 	 * @consumed_modifiers.
349 	 * See [Groups][key-group-explanation] for an explanation of
350 	 * groups and levels. The @effective_group is the group that was
351 	 * actually used for the translation; some keys such as Enter are not
352 	 * affected by the active keyboard group. The @level is derived from
353 	 * @state. For convenience, #GdkEventKey already contains the translated
354 	 * keyval, so this function isn’t as useful as you might think.
355 	 *
356 	 * @consumed_modifiers gives modifiers that should be masked outfrom @state
357 	 * when comparing this key press to a hot key. For instance, on a US keyboard,
358 	 * the `plus` symbol is shifted, so when comparing a key press to a
359 	 * `<Control>plus` accelerator `<Shift>` should be masked out.
360 	 *
361 	 * |[<!-- language="C" -->
362 	 * // We want to ignore irrelevant modifiers like ScrollLock
363 	 * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
364 	 * gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
365 	 * event->state, event->group,
366 	 * &keyval, NULL, NULL, &consumed);
367 	 * if (keyval == GDK_PLUS &&
368 	 * (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
369 	 * // Control was pressed
370 	 * ]|
371 	 *
372 	 * An older interpretation @consumed_modifiers was that it contained
373 	 * all modifiers that might affect the translation of the key;
374 	 * this allowed accelerators to be stored with irrelevant consumed
375 	 * modifiers, by doing:
376 	 * |[<!-- language="C" -->
377 	 * // XXX Don’t do this XXX
378 	 * if (keyval == accel_keyval &&
379 	 * (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
380 	 * // Accelerator was pressed
381 	 * ]|
382 	 *
383 	 * However, this did not work if multi-modifier combinations were
384 	 * used in the keymap, since, for instance, `<Control>` would be
385 	 * masked out even if only `<Control><Alt>` was used in the keymap.
386 	 * To support this usage as well as well as possible, all single
387 	 * modifier combinations that could affect the key for any combination
388 	 * of modifiers will be returned in @consumed_modifiers; multi-modifier
389 	 * combinations are returned only when actually found in @state. When
390 	 * you store accelerators, you should always store them with consumed
391 	 * modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`,
392 	 *
393 	 * Params:
394 	 *     hardwareKeycode = a keycode
395 	 *     state = a modifier state
396 	 *     group = active keyboard group
397 	 *     keyval = return location for keyval, or %NULL
398 	 *     effectiveGroup = return location for effective
399 	 *         group, or %NULL
400 	 *     level = return location for level, or %NULL
401 	 *     consumedModifiers = return location for modifiers
402 	 *         that were used to determine the group or level, or %NULL
403 	 *
404 	 * Return: %TRUE if there was a keyval bound to the keycode/state/group
405 	 */
406 	public bool translateKeyboardState(uint hardwareKeycode, GdkModifierType state, int group, out uint keyval, out int effectiveGroup, out int level, out GdkModifierType consumedModifiers)
407 	{
408 		return gdk_keymap_translate_keyboard_state(gdkKeymap, hardwareKeycode, state, group, &keyval, &effectiveGroup, &level, &consumedModifiers) != 0;
409 	}
410 
411 	int[string] connectedSignals;
412 
413 	void delegate(Keymap)[] onDirectionChangedListeners;
414 	/**
415 	 * The ::direction-changed signal gets emitted when the direction of
416 	 * the keymap changes.
417 	 *
418 	 * Since: 2.0
419 	 */
420 	void addOnDirectionChanged(void delegate(Keymap) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
421 	{
422 		if ( "direction-changed" !in connectedSignals )
423 		{
424 			Signals.connectData(
425 				this,
426 				"direction-changed",
427 				cast(GCallback)&callBackDirectionChanged,
428 				cast(void*)this,
429 				null,
430 				connectFlags);
431 			connectedSignals["direction-changed"] = 1;
432 		}
433 		onDirectionChangedListeners ~= dlg;
434 	}
435 	extern(C) static void callBackDirectionChanged(GdkKeymap* keymapStruct, Keymap _keymap)
436 	{
437 		foreach ( void delegate(Keymap) dlg; _keymap.onDirectionChangedListeners )
438 		{
439 			dlg(_keymap);
440 		}
441 	}
442 
443 	void delegate(Keymap)[] onKeysChangedListeners;
444 	/**
445 	 * The ::keys-changed signal is emitted when the mapping represented by
446 	 * @keymap changes.
447 	 *
448 	 * Since: 2.2
449 	 */
450 	void addOnKeysChanged(void delegate(Keymap) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
451 	{
452 		if ( "keys-changed" !in connectedSignals )
453 		{
454 			Signals.connectData(
455 				this,
456 				"keys-changed",
457 				cast(GCallback)&callBackKeysChanged,
458 				cast(void*)this,
459 				null,
460 				connectFlags);
461 			connectedSignals["keys-changed"] = 1;
462 		}
463 		onKeysChangedListeners ~= dlg;
464 	}
465 	extern(C) static void callBackKeysChanged(GdkKeymap* keymapStruct, Keymap _keymap)
466 	{
467 		foreach ( void delegate(Keymap) dlg; _keymap.onKeysChangedListeners )
468 		{
469 			dlg(_keymap);
470 		}
471 	}
472 
473 	void delegate(Keymap)[] onStateChangedListeners;
474 	/**
475 	 * The ::state-changed signal is emitted when the state of the
476 	 * keyboard changes, e.g when Caps Lock is turned on or off.
477 	 * See gdk_keymap_get_caps_lock_state().
478 	 *
479 	 * Since: 2.16
480 	 */
481 	void addOnStateChanged(void delegate(Keymap) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
482 	{
483 		if ( "state-changed" !in connectedSignals )
484 		{
485 			Signals.connectData(
486 				this,
487 				"state-changed",
488 				cast(GCallback)&callBackStateChanged,
489 				cast(void*)this,
490 				null,
491 				connectFlags);
492 			connectedSignals["state-changed"] = 1;
493 		}
494 		onStateChangedListeners ~= dlg;
495 	}
496 	extern(C) static void callBackStateChanged(GdkKeymap* keymapStruct, Keymap _keymap)
497 	{
498 		foreach ( void delegate(Keymap) dlg; _keymap.onStateChangedListeners )
499 		{
500 			dlg(_keymap);
501 		}
502 	}
503 
504 	/**
505 	 * Obtains the upper- and lower-case versions of the keyval @symbol.
506 	 * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
507 	 *
508 	 * Params:
509 	 *     symbol = a keyval
510 	 *     lower = return location for lowercase version of @symbol
511 	 *     upper = return location for uppercase version of @symbol
512 	 */
513 	public static void keyvalConvertCase(uint symbol, out uint lower, out uint upper)
514 	{
515 		gdk_keyval_convert_case(symbol, &lower, &upper);
516 	}
517 
518 	/**
519 	 * Converts a key name to a key value.
520 	 *
521 	 * The names are the same as those in the
522 	 * `gdk/gdkkeysyms.h` header file
523 	 * but without the leading “GDK_KEY_”.
524 	 *
525 	 * Params:
526 	 *     keyvalName = a key name
527 	 *
528 	 * Return: the corresponding key value, or %GDK_KEY_VoidSymbol
529 	 *     if the key name is not a valid key
530 	 */
531 	public static uint keyvalFromName(string keyvalName)
532 	{
533 		return gdk_keyval_from_name(Str.toStringz(keyvalName));
534 	}
535 
536 	/**
537 	 * Returns %TRUE if the given key value is in lower case.
538 	 *
539 	 * Params:
540 	 *     keyval = a key value.
541 	 *
542 	 * Return: %TRUE if @keyval is in lower case, or if @keyval is not
543 	 *     subject to case conversion.
544 	 */
545 	public static bool keyvalIsLower(uint keyval)
546 	{
547 		return gdk_keyval_is_lower(keyval) != 0;
548 	}
549 
550 	/**
551 	 * Returns %TRUE if the given key value is in upper case.
552 	 *
553 	 * Params:
554 	 *     keyval = a key value.
555 	 *
556 	 * Return: %TRUE if @keyval is in upper case, or if @keyval is not subject to
557 	 *     case conversion.
558 	 */
559 	public static bool keyvalIsUpper(uint keyval)
560 	{
561 		return gdk_keyval_is_upper(keyval) != 0;
562 	}
563 
564 	/**
565 	 * Converts a key value into a symbolic name.
566 	 *
567 	 * The names are the same as those in the
568 	 * `gdk/gdkkeysyms.h` header file
569 	 * but without the leading “GDK_KEY_”.
570 	 *
571 	 * Params:
572 	 *     keyval = a key value
573 	 *
574 	 * Return: a string containing the name
575 	 *     of the key, or %NULL if @keyval is not a valid key. The string
576 	 *     should not be modified.
577 	 */
578 	public static string keyvalName(uint keyval)
579 	{
580 		return Str.toString(gdk_keyval_name(keyval));
581 	}
582 
583 	/**
584 	 * Converts a key value to lower case, if applicable.
585 	 *
586 	 * Params:
587 	 *     keyval = a key value.
588 	 *
589 	 * Return: the lower case form of @keyval, or @keyval itself if it is already
590 	 *     in lower case or it is not subject to case conversion.
591 	 */
592 	public static uint keyvalToLower(uint keyval)
593 	{
594 		return gdk_keyval_to_lower(keyval);
595 	}
596 
597 	/**
598 	 * Convert from a GDK key symbol to the corresponding ISO10646 (Unicode)
599 	 * character.
600 	 *
601 	 * Params:
602 	 *     keyval = a GDK key symbol
603 	 *
604 	 * Return: the corresponding unicode character, or 0 if there
605 	 *     is no corresponding character.
606 	 */
607 	public static uint keyvalToUnicode(uint keyval)
608 	{
609 		return gdk_keyval_to_unicode(keyval);
610 	}
611 
612 	/**
613 	 * Converts a key value to upper case, if applicable.
614 	 *
615 	 * Params:
616 	 *     keyval = a key value.
617 	 *
618 	 * Return: the upper case form of @keyval, or @keyval itself if it is already
619 	 *     in upper case or it is not subject to case conversion.
620 	 */
621 	public static uint keyvalToUpper(uint keyval)
622 	{
623 		return gdk_keyval_to_upper(keyval);
624 	}
625 
626 	/**
627 	 * Convert from a ISO10646 character to a key symbol.
628 	 *
629 	 * Params:
630 	 *     wc = a ISO10646 encoded character
631 	 *
632 	 * Return: the corresponding GDK key symbol, if one exists.
633 	 *     or, if there is no corresponding symbol,
634 	 *     wc | 0x01000000
635 	 */
636 	public static uint unicodeToKeyval(uint wc)
637 	{
638 		return gdk_unicode_to_keyval(wc);
639 	}
640 }