diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index a9b43a3d02..ef29778065 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -6,6 +6,7 @@ gdkdisplay.sgml
gdkdisplaymanager.sgml
gdkscreen.sgml
gdktesting.sgml
+keys.sgml
pixbufs.sgml
regions.sgml
windows.sgml
diff --git a/docs/reference/gdk/tmpl/keys.sgml b/docs/reference/gdk/tmpl/keys.sgml
deleted file mode 100644
index 955086dc38..0000000000
--- a/docs/reference/gdk/tmpl/keys.sgml
+++ /dev/null
@@ -1,345 +0,0 @@
-
-Key Values
-
-
-Functions for manipulating keyboard codes
-
-
-
-Key values are the codes which are sent whenever a key is pressed or released.
-They appear in the keyval field of the
-#GdkEventKey structure, which is passed to signal handlers for the
-"key-press-event" and "key-release-event" signals.
-The complete list of key values can be found in the <gdk/gdkkeysyms.h>
-header file.
-
-
-Key values are regularly updated from the upstream X.org X11 implementation,
-so new values are added regularly. They will be prefixed with GDK_KEY_ rather
-than XF86XK_ or XK_ (for older symbols).
-
-
-Key values can be converted into a string representation using
-gdk_keyval_name(). The reverse function, converting a string to a key value,
-is provided by gdk_keyval_from_name().
-
-
-The case of key values can be determined using gdk_keyval_is_upper() and
-gdk_keyval_is_lower(). Key values can be converted to upper or lower case
-using gdk_keyval_to_upper() and gdk_keyval_to_lower().
-
-
-When it makes sense, key values can be converted to and from
-Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
-
-
-
-One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
-returns the #GdkKeymap for the default display; to obtain keymaps for other
-displays, use gdk_keymap_get_for_display(). A keymap
-is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
-as a representation of a symbol printed on a physical keyboard key. That is, it
-contains three pieces of information. First, it contains the hardware keycode;
-this is an identifying number for a physical key. Second, it contains the
-level of the key. The level indicates which symbol on the
-key will be used, in a vertical direction. So on a standard US keyboard, the key
-with the number "1" on it also has the exclamation point ("!") character on
-it. The level indicates whether to use the "1" or the "!" symbol. The letter
-keys are considered to have a lowercase letter at level 0, and an uppercase
-letter at level 1, though only the uppercase letter is printed. Third, the
-#GdkKeymapKey contains a group; groups are not used on standard US keyboards,
-but are used in many other countries. On a keyboard with groups, there can be 3
-or 4 symbols printed on a single key. The group indicates movement in a
-horizontal direction. Usually groups are used for two different languages. In
-group 0, a key might have two English characters, and in group 1 it might have
-two Hebrew characters. The Hebrew characters will be printed on the key next to
-the English characters.
-
-
-
-In order to use a keymap to interpret a key event, it's necessary to first
-convert the keyboard state into an effective group and level. This is done via a
-set of rules that varies widely according to type of keyboard and user
-configuration. The function gdk_keymap_translate_keyboard_state() accepts a
-keyboard state -- consisting of hardware keycode pressed, active modifiers, and
-active group -- applies the appropriate rules, and returns the group/level to be
-used to index the keymap, along with the modifiers which did not affect the
-group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
-differ from the effective group used for keymap lookups because some keys don't
-have multiple groups - e.g. the Enter key is always in group 0 regardless of
-keyboard state.
-
-
-
-Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
-goes ahead and performs the keymap lookup in addition to telling you which
-effective group/level values were used for the lookup. #GdkEventKey already
-contains this keyval, however, so you don't normally need to call
-gdk_keymap_translate_keyboard_state() just to get the keyval.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-A GdkKeymap defines the translation from keyboard state
-(including a hardware key, a modifier mask, and active keyboard group)
-to a keyval. This translation has two phases. The first phase is
-to determine the effective keyboard group and level for the keyboard
-state; the second phase is to look up the keycode/group/level triplet
-in the keymap and see what keyval it corresponds to.
-
-
-
-
-
-
-
-
-@keymap: the object which received the signal.
-
-
-
-
-
-
-@keymap: the object which received the signal.
-
-
-
-
-
-
-@gdkkeymap: the object which received the signal.
-
-
-
-A GdkKeymapKey is a hardware key that can
-be mapped to a keyval.
-
-
-@keycode: the hardware keycode. This is an identifying number for a
- physical key.
-@group: indicates movement in a horizontal direction. Usually groups are used
- for two different languages. In group 0, a key might have two English
- characters, and in group 1 it might have two Hebrew characters. The Hebrew
- characters will be printed on the key next to the English characters.
-@level: indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number "1" on it also has the
- exclamation point ("!") character on it. The level indicates whether to use
- the "1" or the "!" symbol. The letter keys are considered to have a lowercase
- letter at level 0, and an uppercase letter at level 1, though only the
- uppercase letter is printed.
-
-
-
-
-
-
-@void:
-@Returns:
-
-
-
-
-
-
-
-@display:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@key:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@hardware_keycode:
-@state:
-@group:
-@keyval:
-@effective_group:
-@level:
-@consumed_modifiers:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@keyval:
-@keys:
-@n_keys:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@hardware_keycode:
-@keys:
-@keyvals:
-@n_entries:
-@Returns:
-
-
-
-
-Returns the direction of the keymap.
-
-
-@keymap: a #GdkKeymap or %NULL to use the default keymap.
-Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL.
-@Returns: the direction of the keymap.
-
-
-
-
-
-
-
-@keymap:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@Returns:
-
-
-
-
-
-
-
-@keymap:
-@state:
-
-
-
-
-
-
-
-@keymap:
-@state:
-@Returns:
-
-
-
-
-Converts a key name to a key value.
-
-
-@keyval_name: a key name.
-@Returns: the corresponding key value, or %GDK_VoidSymbol if the key name is
-not a valid key.
-
-
-
-
-
-
-
-@symbol:
-@lower:
-@upper:
-
-
-
-
-Converts a key value to upper case, if applicable.
-
-
-@keyval: a key value.
-@Returns: the upper case form of @keyval, or @keyval itself if it is already
-in upper case or it is not subject to case conversion.
-
-
-
-
-Converts a key value to lower case, if applicable.
-
-
-@keyval: a key value.
-@Returns: the lower case form of @keyval, or @keyval itself if it is already
-in lower case or it is not subject to case conversion.
-
-
-
-
-Returns %TRUE if the given key value is in upper case.
-
-
-@keyval: a key value.
-@Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
-case conversion.
-
-
-
-
-Returns %TRUE if the given key value is in lower case.
-
-
-@keyval: a key value.
-@Returns: %TRUE if @keyval is in lower case, or if @keyval is not subject to
-case conversion.
-
-
-
-
-
-
-
-@keyval:
-@Returns:
-
-
-
-
-
-
-
-@wc:
-@Returns:
-
-
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 872576f6d3..e72b8eab98 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -31,6 +31,76 @@
#include "gdkdisplay.h"
+/**
+ * SECTION:keys
+ * @Short_description: Functions for manipulating keyboard codes
+ * @Title: Key Values
+ *
+ * Key values are the codes which are sent whenever a key is pressed or released.
+ * They appear in the #GdkEventKey.keyval field of the
+ * #GdkEventKey structure, which is passed to signal handlers for the
+ * #GtkWidget::key-press-event and #GtkWidget::key-release-event signals.
+ * The complete list of key values can be found in the
+ * <gdk/gdkkeysyms.h> header file.
+ *
+ * Key values are regularly updated from the upstream X.org X11 implementation,
+ * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
+ * than XF86XK_ or XK_ (for older symbols).
+ *
+ * Key values can be converted into a string representation using
+ * gdk_keyval_name(). The reverse function, converting a string to a key value,
+ * is provided by gdk_keyval_from_name().
+ *
+ * The case of key values can be determined using gdk_keyval_is_upper() and
+ * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
+ * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
+ *
+ * When it makes sense, key values can be converted to and from
+ * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
+ *
+ *
+ * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
+ * returns the #GdkKeymap for the default display; to obtain keymaps for other
+ * displays, use gdk_keymap_get_for_display(). A keymap
+ * is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
+ * as a representation of a symbol printed on a physical keyboard key. That is, it
+ * contains three pieces of information. First, it contains the hardware keycode;
+ * this is an identifying number for a physical key. Second, it contains the
+ * level of the key. The level indicates which symbol on the
+ * key will be used, in a vertical direction. So on a standard US keyboard, the key
+ * with the number "1" on it also has the exclamation point ("!") character on
+ * it. The level indicates whether to use the "1" or the "!" symbol. The letter
+ * keys are considered to have a lowercase letter at level 0, and an uppercase
+ * letter at level 1, though only the uppercase letter is printed. Third, the
+ * #GdkKeymapKey contains a group; groups are not used on standard US keyboards,
+ * but are used in many other countries. On a keyboard with groups, there can be 3
+ * or 4 symbols printed on a single key. The group indicates movement in a
+ * horizontal direction. Usually groups are used for two different languages. In
+ * group 0, a key might have two English characters, and in group 1 it might have
+ * two Hebrew characters. The Hebrew characters will be printed on the key next to
+ * the English characters.
+ *
+ *
+ * In order to use a keymap to interpret a key event, it's necessary to first
+ * convert the keyboard state into an effective group and level. This is done via a
+ * set of rules that varies widely according to type of keyboard and user
+ * configuration. The function gdk_keymap_translate_keyboard_state() accepts a
+ * keyboard state -- consisting of hardware keycode pressed, active modifiers, and
+ * active group -- applies the appropriate rules, and returns the group/level to be
+ * used to index the keymap, along with the modifiers which did not affect the
+ * group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
+ * differ from the effective group used for keymap lookups because some keys don't
+ * have multiple groups - e.g. the Enter key is always in group 0 regardless of
+ * keyboard state.
+ *
+ * Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
+ * goes ahead and performs the keymap lookup in addition to telling you which
+ * effective group/level values were used for the lookup. #GdkEventKey already
+ * contains this keyval, however, so you don't normally need to call
+ * gdk_keymap_translate_keyboard_state() just to get the keyval.
+ */
+
+
enum {
DIRECTION_CHANGED,
KEYS_CHANGED,
@@ -255,6 +325,15 @@ gdk_keyval_convert_case (guint symbol,
}
#endif
+/**
+ * gdk_keyval_to_upper:
+ * @keyval: a key value.
+ *
+ * Converts a key value to upper case, if applicable.
+ *
+ * Returns: the upper case form of @keyval, or @keyval itself if it is already
+ * in upper case or it is not subject to case conversion.
+ */
guint
gdk_keyval_to_upper (guint keyval)
{
@@ -265,6 +344,15 @@ gdk_keyval_to_upper (guint keyval)
return result;
}
+/**
+ * gdk_keyval_to_lower:
+ * @keyval: a key value.
+ *
+ * Converts a key value to lower case, if applicable.
+ *
+ * Returns: the lower case form of @keyval, or @keyval itself if it is already
+ * in lower case or it is not subject to case conversion.
+ */
guint
gdk_keyval_to_lower (guint keyval)
{
@@ -275,6 +363,15 @@ gdk_keyval_to_lower (guint keyval)
return result;
}
+/**
+ * gdk_keyval_is_upper:
+ * @keyval: a key value.
+ *
+ * Returns %TRUE if the given key value is in upper case.
+ *
+ * Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
+ * case conversion.
+ */
gboolean
gdk_keyval_is_upper (guint keyval)
{
@@ -288,6 +385,15 @@ gdk_keyval_is_upper (guint keyval)
return FALSE;
}
+/**
+ * gdk_keyval_is_lower:
+ * @keyval: a key value.
+ *
+ * Returns %TRUE if the given key value is in lower case.
+ *
+ * Returns: %TRUE if @keyval is in lower case, or if @keyval is not
+ * subject to case conversion.
+ */
gboolean
gdk_keyval_is_lower (guint keyval)
{
@@ -303,10 +409,11 @@ gdk_keyval_is_lower (guint keyval)
/**
* gdk_keymap_get_default:
- * @returns: the #GdkKeymap attached to the default display.
*
* Returns the #GdkKeymap attached to the default display.
- **/
+ *
+ * Returns: the #GdkKeymap attached to the default display.
+ */
GdkKeymap*
gdk_keymap_get_default (void)
{
diff --git a/gdk/gdkkeys.h b/gdk/gdkkeys.h
index 212c680a7c..4551b98905 100644
--- a/gdk/gdkkeys.h
+++ b/gdk/gdkkeys.h
@@ -35,9 +35,26 @@
G_BEGIN_DECLS
+
typedef struct _GdkKeymapKey GdkKeymapKey;
-/* GdkKeymapKey is a hardware key that can be mapped to a keyval */
+/**
+ * GdkKeymapKey:
+ * @keycode: the hardware keycode. This is an identifying number for a
+ * physical key.
+ * @group: indicates movement in a horizontal direction. Usually groups are used
+ * for two different languages. In group 0, a key might have two English
+ * characters, and in group 1 it might have two Hebrew characters. The Hebrew
+ * characters will be printed on the key next to the English characters.
+ * @level: indicates which symbol on the key will be used, in a vertical direction.
+ * So on a standard US keyboard, the key with the number "1" on it also has the
+ * exclamation point ("!") character on it. The level indicates whether to use
+ * the "1" or the "!" symbol. The letter keys are considered to have a lowercase
+ * letter at level 0, and an uppercase letter at level 1, though only the
+ * uppercase letter is printed.
+ *
+ * A #GdkKeymapKey is a hardware key that can be mapped to a keyval.
+ */
struct _GdkKeymapKey
{
guint keycode;
@@ -45,16 +62,6 @@ struct _GdkKeymapKey
gint level;
};
-/* A GdkKeymap defines the translation from keyboard state
- * (including a hardware key, a modifier mask, and active keyboard group)
- * to a keyval. This translation has two phases. The first phase is
- * to determine the effective keyboard group and level for the keyboard
- * state; the second phase is to look up the keycode/group/level triplet
- * in the keymap and see what keyval it corresponds to.
- */
-
-typedef struct _GdkKeymap GdkKeymap;
-typedef struct _GdkKeymapClass GdkKeymapClass;
#define GDK_TYPE_KEYMAP (gdk_keymap_get_type ())
#define GDK_KEYMAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), GDK_TYPE_KEYMAP, GdkKeymap))
@@ -63,6 +70,19 @@ typedef struct _GdkKeymapClass GdkKeymapClass;
#define GDK_IS_KEYMAP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GDK_TYPE_KEYMAP))
#define GDK_KEYMAP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GDK_TYPE_KEYMAP, GdkKeymapClass))
+typedef struct _GdkKeymap GdkKeymap;
+typedef struct _GdkKeymapClass GdkKeymapClass;
+
+/**
+ * GdkKeymap:
+ *
+ * A #GdkKeymap defines the translation from keyboard state
+ * (including a hardware key, a modifier mask, and active keyboard group)
+ * to a keyval. This translation has two phases. The first phase is
+ * to determine the effective keyboard group and level for the keyboard
+ * state; the second phase is to look up the keycode/group/level triplet
+ * in the keymap and see what keyval it corresponds to.
+ */
struct _GdkKeymap
{
GObject parent_instance;
@@ -105,6 +125,16 @@ gboolean gdk_keymap_get_entries_for_keycode (GdkKeymap *keymap,
GdkKeymapKey **keys,
guint **keyvals,
gint *n_entries);
+
+/**
+ * gdk_keymap_get_direction:
+ * @keymap: a #GdkKeymap or %NULL to use the default keymap.
+ *
+ * Returns the direction of the keymap.
+ *
+ * Returns: the direction of the keymap, %PANGO_DIRECTION_LTR or
+ * %PANGO_DIRECTION_RTL.
+ */
PangoDirection gdk_keymap_get_direction (GdkKeymap *keymap);
gboolean gdk_keymap_have_bidi_layouts (GdkKeymap *keymap);
gboolean gdk_keymap_get_caps_lock_state (GdkKeymap *keymap);
@@ -117,6 +147,16 @@ gboolean gdk_keymap_map_virtual_modifiers (GdkKeymap *keymap,
/* Key values
*/
gchar* gdk_keyval_name (guint keyval) G_GNUC_CONST;
+
+/**
+ * gdk_keyval_from_name:
+ * @keyval_name: a key name.
+ *
+ * Converts a key name to a key value.
+ *
+ * Returns: the corresponding key value, or %GDK_VoidSymbol if the key name is
+ * not a valid key.
+ */
guint gdk_keyval_from_name (const gchar *keyval_name);
void gdk_keyval_convert_case (guint symbol,
guint *lower,