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