keys.sgml 8.6 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
Key Values

<!-- ##### SECTION Short_Description ##### -->
5
Functions for manipulating keyboard codes
Owen Taylor's avatar
Owen Taylor committed
6 7 8 9 10 11 12

<!-- ##### SECTION Long_Description ##### -->
<para>
Key values are the codes which are sent whenever a key is pressed or released.
They appear in the <structfield>keyval</structfield> field of the
#GdkEventKey structure, which is passed to signal handlers for the
"key-press-event" and "key-release-event" signals.
Matthias Clasen's avatar
Matthias Clasen committed
13 14
The complete list of key values can be found in the <filename>&lt;gdk/gdkkeysyms.h&gt;</filename>
header file. <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> is not included in <filename>&lt;gtk/gtk.h&gt;</filename>, 
Havoc Pennington's avatar
Havoc Pennington committed
15
it must be included independently, because the file is quite large.
Owen Taylor's avatar
Owen Taylor committed
16 17 18 19 20 21 22 23 24 25
</para>
<para>
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().
</para>
<para>
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().
Havoc Pennington's avatar
Havoc Pennington committed
26 27 28 29 30 31 32
</para>
<para>
When it makes sense, key values can be converted to and from 
Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
</para>

<para>
33 34 35
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
Havoc Pennington's avatar
Havoc Pennington committed
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
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
<firstterm>level</firstterm> 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.
</para>

<para>
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.
</para>

<para>
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.

Owen Taylor's avatar
Owen Taylor committed
76 77 78 79 80 81 82
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

Matthias Clasen's avatar
2.7.0  
Matthias Clasen committed
83 84 85
<!-- ##### SECTION Stability_Level ##### -->


Havoc Pennington's avatar
Havoc Pennington committed
86 87
<!-- ##### STRUCT GdkKeymap ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
88 89 90 91 92 93
A <structname>GdkKeymap</structname> 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.
Havoc Pennington's avatar
Havoc Pennington committed
94 95 96
</para>


Soeren Sandmann's avatar
Soeren Sandmann committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110
<!-- ##### SIGNAL GdkKeymap::direction-changed ##### -->
<para>

</para>

@keymap: the object which received the signal.

<!-- ##### SIGNAL GdkKeymap::keys-changed ##### -->
<para>

</para>

@keymap: the object which received the signal.

Havoc Pennington's avatar
Havoc Pennington committed
111 112
<!-- ##### STRUCT GdkKeymapKey ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
113 114
A <structname>GdkKeymapKey</structname> is a hardware key that can 
be mapped to a keyval.
Havoc Pennington's avatar
Havoc Pennington committed
115 116
</para>

Matthias Clasen's avatar
Matthias Clasen committed
117 118 119 120 121 122 123 124 125 126
@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 
Owen Taylor's avatar
Owen Taylor committed
127
  uppercase letter is printed.
Havoc Pennington's avatar
Havoc Pennington committed
128 129 130 131 132 133 134 135 136

<!-- ##### FUNCTION gdk_keymap_get_default ##### -->
<para>

</para>

@Returns: 


Owen Taylor's avatar
Owen Taylor committed
137 138 139 140 141 142 143 144 145
<!-- ##### FUNCTION gdk_keymap_get_for_display ##### -->
<para>

</para>

@display: 
@Returns: 


Havoc Pennington's avatar
Havoc Pennington committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
<!-- ##### FUNCTION gdk_keymap_lookup_key ##### -->
<para>

</para>

@keymap: 
@key: 
@Returns: 


<!-- ##### FUNCTION gdk_keymap_translate_keyboard_state ##### -->
<para>

</para>

@keymap: 
@hardware_keycode: 
@state: 
@group: 
@keyval: 
@effective_group: 
@level: 
168
@consumed_modifiers: 
Havoc Pennington's avatar
Havoc Pennington committed
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
@Returns: 


<!-- ##### FUNCTION gdk_keymap_get_entries_for_keyval ##### -->
<para>

</para>

@keymap: 
@keyval: 
@keys: 
@n_keys: 
@Returns: 


<!-- ##### FUNCTION gdk_keymap_get_entries_for_keycode ##### -->
<para>

</para>

@keymap: 
@hardware_keycode: 
@keys: 
@keyvals: 
@n_entries: 
@Returns: 


Havoc Pennington's avatar
Havoc Pennington committed
197 198
<!-- ##### FUNCTION gdk_keymap_get_direction ##### -->
<para>
Matthias Clasen's avatar
Update.  
Matthias Clasen committed
199
Returns the direction of the keymap. 
Havoc Pennington's avatar
Havoc Pennington committed
200 201
</para>

Matthias Clasen's avatar
Update.  
Matthias Clasen committed
202 203
@keymap: a #GdkKeymap or %NULL to use the default keymap.
Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL.
204
@Returns: the direction of the keymap.
Havoc Pennington's avatar
Havoc Pennington committed
205 206


Matthias Clasen's avatar
2.11.5  
Matthias Clasen committed
207 208 209 210 211 212 213 214 215
<!-- ##### FUNCTION gdk_keymap_have_bidi_layouts ##### -->
<para>

</para>

@keymap: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
216 217 218
<!-- ##### FUNCTION gdk_keyval_name ##### -->
<para>
Converts a key value into a symbolic name.
Matthias Clasen's avatar
Matthias Clasen committed
219
The names are the same as those in the <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file
Owen Taylor's avatar
Owen Taylor committed
220 221 222 223
but without the leading "GDK_".
</para>

@keyval: a key value.
Matthias Clasen's avatar
Matthias Clasen committed
224
@Returns: a string containing the name of the key, or %NULL if @keyval is not
Owen Taylor's avatar
Owen Taylor committed
225 226 227 228 229 230 231 232 233 234 235 236 237
a valid key. The string should not be modified.


<!-- ##### FUNCTION gdk_keyval_from_name ##### -->
<para>
Converts a key name to a key value.
</para>

@keyval_name: a key name.
@Returns: the corresponding key value, or %GDK_VoidSymbol if the key name is
not a valid key.


238 239 240 241 242 243 244 245 246 247
<!-- ##### FUNCTION gdk_keyval_convert_case ##### -->
<para>

</para>

@symbol: 
@lower: 
@upper: 


Owen Taylor's avatar
Owen Taylor committed
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267
<!-- ##### FUNCTION gdk_keyval_to_upper ##### -->
<para>
Converts a key value to upper case, if applicable.
</para>

@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.


<!-- ##### FUNCTION gdk_keyval_to_lower ##### -->
<para>
Converts a key value to lower case, if applicable.
</para>

@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.


Owen Taylor's avatar
Owen Taylor committed
268 269
<!-- ##### FUNCTION gdk_keyval_is_upper ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
270
Returns %TRUE if the given key value is in upper case.
Owen Taylor's avatar
Owen Taylor committed
271 272 273
</para>

@keyval: a key value.
Matthias Clasen's avatar
Matthias Clasen committed
274
@Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
Owen Taylor's avatar
Owen Taylor committed
275 276 277 278 279
case conversion.


<!-- ##### FUNCTION gdk_keyval_is_lower ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
280
Returns %TRUE if the given key value is in lower case.
Owen Taylor's avatar
Owen Taylor committed
281 282 283
</para>

@keyval: a key value.
Matthias Clasen's avatar
Matthias Clasen committed
284
@Returns: %TRUE if @keyval is in lower case, or if @keyval is not subject to
Owen Taylor's avatar
Owen Taylor committed
285 286 287
case conversion.


288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305
<!-- ##### FUNCTION gdk_keyval_to_unicode ##### -->
<para>

</para>

@keyval: 
@Returns: 


<!-- ##### FUNCTION gdk_unicode_to_keyval ##### -->
<para>

</para>

@wc: 
@Returns: