[gtk/keymap-rework-2: 9/34] Move keymap mapping functions to GdkDisplay

[Matthias Clasen <matthiasc src gnome org>]

commit 00b25d55948c83d5ffd72ea35149bb2ce23cfa82
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Apr 5 11:02:50 2020 -0400

    Move keymap mapping functions to GdkDisplay
    
    We want to stop exposing GdkKeymap, so this
    functionality needs a new home.

 docs/reference/gdk/gdk4-sections.txt |  4 ++
 gdk/gdkdisplay.c                     | 72 ++++++++++++++++++++++++++++++++++++
 gdk/gdkdisplay.h                     | 13 +++++++
 3 files changed, 89 insertions(+)
---
diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index 553982ca50..64c9b98ffc 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -100,6 +100,10 @@ gdk_display_get_primary_clipboard
 gdk_display_get_setting
 gdk_display_get_keymap
 
+<SUBSECTION>
+gdk_display_map_keyval
+gdk_display_map_keycode
+
 <SUBSECTION Standard>
 GDK_DISPLAY
 GDK_DISPLAY_OBJECT
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index ce3963a542..8155b01e0b 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -1718,3 +1718,75 @@ gdk_display_get_modifier_mask (GdkDisplay        *display,
 {
   return gdk_keymap_get_modifier_mask (gdk_display_get_keymap (display), intent);  
 }
+
+/**
+ * gdk_display_map_keyval:
+ * @display: a #GdkDisplay
+ * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
+ * @keys: (out) (array length=n_keys) (transfer full): return location
+ *     for an array of #GdkKeymapKey
+ * @n_keys: return location for number of elements in returned array
+ *
+ * Obtains a list of keycode/group/level combinations that will
+ * generate @keyval. Groups and levels are two kinds of keyboard mode;
+ * in general, the level determines whether the top or bottom symbol
+ * on a key is used, and the group determines whether the left or
+ * right symbol is used.
+ *
+ * On US keyboards, the shift key changes the keyboard level, and there
+ * are no groups. A group switch key might convert a keyboard between
+ * Hebrew to English modes, for example.
+ *
+ * #GdkEventKey contains a %group field that indicates the active
+ * keyboard group. The level is computed from the modifier mask.
+ *
+ * The returned array should be freed with g_free().
+ *
+ * Returns: %TRUE if keys were found and returned
+ */
+gboolean
+gdk_display_map_keyval (GdkDisplay    *display,
+                        guint          keyval,
+                        GdkKeymapKey **keys,
+                        int           *n_keys)
+{
+  return gdk_keymap_get_entries_for_keyval (gdk_display_get_keymap (display),
+                                            keyval,
+                                            keys,
+                                            n_keys);
+}
+
+/**
+ * gdk_display_map_keycode:
+ * @display: a #GdkDisplay
+ * @keycode: a keycode
+ * @keys: (out) (array length=n_entries) (transfer full) (optional): return
+ *     location for array of #GdkKeymapKey, or %NULL
+ * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
+ *     location for array of keyvals, or %NULL
+ * @n_entries: length of @keys and @keyvals
+ *
+ * Returns the keyvals bound to @keycode. The Nth #GdkKeymapKey
+ * in @keys is bound to the Nth keyval in @keyvals.
+ *
+ * When a keycode is pressed by the user, the keyval from
+ * this list of entries is selected by considering the effective
+ * keyboard group and level.
+ *
+ * Free the returned arrays with g_free().
+ *
+ * Returns: %TRUE if there were any entries
+ */
+gboolean
+gdk_display_map_keycode (GdkDisplay    *display,
+                         guint          keycode,
+                         GdkKeymapKey **keys,
+                         guint        **keyvals,
+                         int           *n_entries)
+{
+  return gdk_keymap_get_entries_for_keycode (gdk_display_get_keymap (display),
+                                             keycode,
+                                             keys,
+                                             keyvals,
+                                             n_entries);
+}
diff --git a/gdk/gdkdisplay.h b/gdk/gdkdisplay.h
index 8d9aace402..5e70e7e047 100644
--- a/gdk/gdkdisplay.h
+++ b/gdk/gdkdisplay.h
@@ -122,6 +122,19 @@ GDK_AVAILABLE_IN_ALL
 GdkModifierType gdk_display_get_modifier_mask (GdkDisplay        *display,
                                                GdkModifierIntent  intent);
 
+GDK_AVAILABLE_IN_ALL
+gboolean       gdk_display_map_keyval  (GdkDisplay    *display,
+                                        guint          keyval,
+                                        GdkKeymapKey **keys,
+                                        int           *n_keys);
+
+GDK_AVAILABLE_IN_ALL
+gboolean       gdk_display_map_keycode (GdkDisplay    *display,
+                                        guint          keycode,
+                                        GdkKeymapKey **keys,
+                                        guint        **keyvals,
+                                        int           *n_entries);
+
 GDK_AVAILABLE_IN_ALL
 gboolean     gdk_display_get_setting (GdkDisplay *display,
                                       const char *name,