
@c %start of fragment

@deftp Class <gdk-keymap>
This @code{<gobject>} class defines no properties, other than those defined by
its superclasses.

@end deftp

@defop Signal <gdk-keymap> direction-changed 
The ::direction_changed signal gets emitted when the direction of the keymap
changes.

Since 2.0

@end defop

@defop Signal <gdk-keymap> keys-changed 
The ::keys_changed signal is emitted when the mapping represented by
@var{keymap} changes.

Since 2.2

@end defop

@deffn Function gdk-keymap-get-default  @result{}@tie{} (ret@tie{}@code{<gdk-keymap>})
Returns the @code{<gdk-keymap>} attached to the default display.

@table @var
@item ret
the @code{<gdk-keymap>} attached to the default display.

@end table

@end deffn

@deffn Function gdk-keymap-get-for-display  (display@tie{}@code{<gdk-display>}) @result{}@tie{} (ret@tie{}@code{<gdk-keymap>})
Returns the @code{<gdk-keymap>} attached to @var{display}.

@table @var
@item display
the @code{<gdk-display>}.

@item ret
the @code{<gdk-keymap>} attached to @var{display}.

@end table

Since 2.2

@end deffn

@deffn Function gdk-keymap-lookup-key  (self@tie{}@code{<gdk-keymap>}) (key@tie{}@code{<gdk-keymap-key*>}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
@deffnx Method lookup-key
Looks up the keyval mapped to a keycode/group/level triplet. If no keyval is
bound to @var{key}, returns 0. For normal user input, you want to use
@code{gdk-keymap-translate-keyboard-state} instead of this function, since the
effective group/level may not be the same as the current keyboard state.

@table @var
@item keymap
a @code{<gdk-keymap>} or @samp{@code{#f}} to use the default keymap

@item key
a @code{<gdk-keymap-key>} with keycode, group, and level initialized

@item ret
a keyval, or 0 if none was mapped to the given @var{key}

@end table

@end deffn

@deffn Function gdk-keymap-translate-keyboard-state  (self@tie{}@code{<gdk-keymap>}) (hardware_keycode@tie{}@code{unsigned-int}) (state@tie{}@code{<gdk-modifier-type>}) (group@tie{}@code{int}) (consumed_modifiers@tie{}@code{<gdk-modifier-type*>}) @result{}@tie{} (ret@tie{}@code{bool}) (keyval@tie{}@code{unsigned-int}) (effective_group@tie{}@code{int}) (level@tie{}@code{int})
@deffnx Method translate-keyboard-state
Translates the contents of a @code{<gdk-event-key>} into a keyval, effective
group, and level. Modifiers that affected the translation and are thus
unavailable for application use are returned in @var{consumed-modifiers}. See
@code{gdk-keyval-get-keys} for an explanation of groups and levels. The
@var{effective-group} is the group that was actually used for the translation;
some keys such as Enter are not affected by the active keyboard group. The
@var{level} is derived from @var{state}. For convenience, @code{<gdk-event-key>}
already contains the translated keyval, so this function isn't as useful as you
might think.



@var{consumed-modifiers} gives modifiers that should be masked out from
@var{state} when comparing this key press to a hot key. For instance, on a US
keyboard, the @samp{plus} symbol is shifted, so when comparing a key press to a
@samp{<Control>plus} accelerator <Shift> should be masked out.

@example 

/* We want to ignore irrelevant modifiers like ScrollLock */
&#x0023;define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
                                     event->state, event->group,
                                     &keyval, NULL, NULL, &consumed);
if (keyval == GDK_PLUS &&
    (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
  /* Control was pressed */
@end example

An older interpretation @var{consumed-modifiers} was that it contained all
modifiers that might affect the translation of the key; this allowed
accelerators to be stored with irrelevant consumed modifiers, by doing:

@example 

/* XXX Don't do this XXX */
if (keyval == accel_keyval &&
    (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
  /* Accelerator was pressed */
@end example

However, this did not work if multi-modifier combinations were used in the
keymap, since, for instance, @samp{<Control>} would be masked out even if only
@samp{<Control><Alt>} was used in the keymap. To support this usage as well as
well as possible, all @emph{single modifier} combinations that could affect the
key for any combination of modifiers will be returned in
@var{consumed-modifiers}; multi-modifier combinations are returned only when
actually found in @var{state}. When you store accelerators, you should always
store them with consumed modifiers removed. Store @samp{<Control>plus}, not
@samp{<Control><Shift>plus},

@table @var
@item keymap
a @code{<gdk-keymap>}, or @samp{@code{#f}} to use the default

@item hardware-keycode
a keycode

@item state
a modifier state

@item group
active keyboard group

@item keyval
return location for keyval

@item effective-group
return location for effective group

@item level
return location for level

@item consumed-modifiers
return location for modifiers that were used to determine the group or level

@item ret
@samp{@code{#t}} if there was a keyval bound to the keycode/state/group

@end table

@end deffn

@deffn Function gdk-keymap-get-entries-for-keyval  (self@tie{}@code{<gdk-keymap>}) (keyval@tie{}@code{unsigned-int}) (keys@tie{}@code{<gdk-keymap-key**>}) @result{}@tie{} (ret@tie{}@code{bool}) (n_keys@tie{}@code{int})
@deffnx Method get-entries-for-keyval
Obtains a list of keycode/group/level combinations that will generate
@var{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.
@code{<gdk-event-key>} contains a @samp{group} field that indicates the active
keyboard group. The level is computed from the modifier mask. The returned array
should be freed with @code{g-free}.

@table @var
@item keymap
a @code{<gdk-keymap>}, or @samp{@code{#f}} to use the default keymap

@item keyval
a keyval, such as @samp{GDK_a}, @samp{GDK_Up}, @samp{GDK_Return}, etc.

@item keys
return location for an array of @code{<gdk-keymap-key>}

@item n-keys
return location for number of elements in returned array

@item ret
@samp{@code{#t}} if keys were found and returned

@end table

@end deffn

@deffn Function gdk-keymap-get-entries-for-keycode  (self@tie{}@code{<gdk-keymap>}) (hardware_keycode@tie{}@code{unsigned-int}) (keys@tie{}@code{<gdk-keymap-key**>}) (keyvals@tie{}@code{<guint**>}) @result{}@tie{} (ret@tie{}@code{bool}) (n_entries@tie{}@code{int})
@deffnx Method get-entries-for-keycode
Returns the keyvals bound to @var{hardware-keycode}. The Nth
@code{<gdk-keymap-key>} in @var{keys} is bound to the Nth keyval in
@var{keyvals}. Free the returned arrays with @code{g-free}. 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. See
@code{gdk-keymap-translate-keyboard-state}.

@table @var
@item keymap
a @code{<gdk-keymap>} or @samp{@code{#f}} to use the default keymap

@item hardware-keycode
a keycode

@item keys
return location for array of @code{<gdk-keymap-key>}, or NULL

@item keyvals
return location for array of keyvals, or NULL

@item n-entries
length of @var{keys} and @var{keyvals}

@item ret
@samp{@code{#t}} if there were any entries

@end table

@end deffn

@deffn Function gdk-keymap-get-direction  (self@tie{}@code{<gdk-keymap>}) @result{}@tie{} (ret@tie{}@code{<pango-direction>})
@deffnx Method get-direction
Returns the direction of the keymap.

@table @var
@item keymap
a @code{<gdk-keymap>} or @samp{@code{#f}} to use the default keymap. Returns:
@samp{PANGO_DIRECTION_LTR} or @samp{PANGO_DIRECTION_RTL}.

@item ret
the direction of the keymap.

@end table

@end deffn

@deffn Function gdk-keyval-name  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a key value into a symbolic name. The names are the same as those in
the @file{<gdk/gdkkeysyms.h>} header file but without the leading "GDK_".

@table @var
@item keyval
a key value.

@item ret
a string containing the name of the key, or @samp{@code{#f}} if @var{keyval} is
not a valid key. The string should not be modified.

@end table

@end deffn

@deffn Function gdk-keyval-from-name  (keyval_name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
Converts a key name to a key value.

@table @var
@item keyval-name
a key name.

@item ret
the corresponding key value, or @samp{GDK_VoidSymbol} if the key name is not a
valid key.

@end table

@end deffn

@deffn Function gdk-keyval-convert-case  (symbol@tie{}@code{unsigned-int}) @result{}@tie{} (lower@tie{}@code{unsigned-int}) (upper@tie{}@code{unsigned-int})
Obtains the upper- and lower-case versions of the keyval @var{symbol}. Examples
of keyvals are @code{<gdk-a>}, @code{<gdk--enter>}, @code{<gdk-f1>}, etc.

@table @var
@item symbol
a keyval

@item lower
return location for lowercase version of @var{symbol}

@item upper
return location for uppercase version of @var{symbol}

@end table

@end deffn

@deffn Function gdk-keyval-to-upper  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
Converts a key value to upper case, if applicable.

@table @var
@item keyval
a key value.

@item ret
the upper case form of @var{keyval}, or @var{keyval} itself if it is already in
upper case or it is not subject to case conversion.

@end table

@end deffn

@deffn Function gdk-keyval-to-lower  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
Converts a key value to lower case, if applicable.

@table @var
@item keyval
a key value.

@item ret
the lower case form of @var{keyval}, or @var{keyval} itself if it is already in
lower case or it is not subject to case conversion.

@end table

@end deffn

@deffn Function gdk-keyval-is-upper  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{bool})
Returns @samp{@code{#t}} if the given key value is in upper case.

@table @var
@item keyval
a key value.

@item ret
@samp{@code{#t}} if @var{keyval} is in upper case, or if @var{keyval} is not
subject to case conversion.

@end table

@end deffn

@deffn Function gdk-keyval-is-lower  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{bool})
Returns @samp{@code{#t}} if the given key value is in lower case.

@table @var
@item keyval
a key value.

@item ret
@samp{@code{#t}} if @var{keyval} is in lower case, or if @var{keyval} is not
subject to case conversion.

@end table

@end deffn

@deffn Function gdk-keyval-to-unicode  (keyval@tie{}@code{unsigned-int}) @result{}@tie{} (ret@tie{}@code{unsigned-int32})
Convert from a GDK key symbol to the corresponding ISO10646 (Unicode) character.

@table @var
@item keyval
a GDK key symbol

@item ret
the corresponding unicode character, or 0 if there is no corresponding
character.

@end table

@end deffn

@deffn Function gdk-unicode-to-keyval  (wc@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
Convert from a ISO10646 character to a key symbol.

@table @var
@item wc
a ISO10646 encoded character

@item ret
the corresponding GDK key symbol, if one exists. or, if there is no
corresponding symbol, wc | 0x01000000

@end table

@end deffn


@c %end of fragment
