callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

New upstream version 3.24.18

Browse Source
This commit is contained in:
Simon McVittie
2020-04-10 15:23:16 +01:00
parent ecf5b7f34b f9decb0cd6
commit ea8a581be2
386 changed files with 78008 additions and 6390 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/reference/gdk/html/gdk3-Keyboard-Handling.html
View File

@ -155,7 +155,7 @@
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">GdkModifierType</span>
<a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="returnvalue">GdkModifierType</span></a>
</td>
<td class="function_name">
<a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-get-modifier-mask" title="gdk_keymap_get_modifier_mask ()">gdk_keymap_get_modifier_mask</a> <span class="c_punctuation">()</span>
@ -273,11 +273,11 @@
<tbody>
<tr>
<td class="datatype_keyword"> </td>
<td class="function_name">GdkKeymap</td>
<td class="function_name"><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap-struct" title="GdkKeymap">GdkKeymap</a></td>
</tr>
<tr>
<td class="datatype_keyword">struct</td>
<td class="function_name">GdkKeymapKey</td>
<td class="function_name"><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey">GdkKeymapKey</a></td>
</tr>
</tbody>
</table></div>
@ -296,8 +296,8 @@
<div class="refsect1">
<a name="gdk3-Keyboard-Handling.description"></a><h2>Description</h2>
<p>Key values are the codes which are sent whenever a key is pressed or released.
They appear in the <span class="type">GdkEventKey.keyval</span> field of the
<span class="type">GdkEventKey</span> structure, which is passed to signal handlers for the
They appear in the <a class="link" href="gdk3-Event-Structures.html#GdkEventKey.keyval"><span class="type">GdkEventKey.keyval</span></a> field of the
<a class="link" href="gdk3-Event-Structures.html#GdkEventKey" title="struct GdkEventKey"><span class="type">GdkEventKey</span></a> structure, which is passed to signal handlers for the
<span class="type">“key-press-event”</span> and <span class="type">“key-release-event”</span> signals.
The complete list of key values can be found in the
<code class="literal">gdk/gdkkeysyms.h</code> header file.</p>
@ -317,7 +317,7 @@ Unicode characters with <a class="link" href="gdk3-Keyboard-Handling.html#gdk-ke
<p>One <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> object exists for each user display. <a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-get-default" title="gdk_keymap_get_default ()"><code class="function">gdk_keymap_get_default()</code></a>
returns the <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> for the default display; to obtain keymaps for other
displays, use <a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-get-for-display" title="gdk_keymap_get_for_display ()"><code class="function">gdk_keymap_get_for_display()</code></a>. A keymap
is a mapping from <span class="type">GdkKeymapKey</span> to key values. You can think of a <span class="type">GdkKeymapKey</span>
is a mapping from <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> to key values. You can think of a <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a>
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
@ -327,7 +327,7 @@ with the number “1“ on it also has the exclamation point (”!”) character
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
<span class="type">GdkKeymapKey</span> contains a group; groups are not used on standard US keyboards,
<a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> 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
@ -347,7 +347,7 @@ have multiple groups - e.g. the Enter key is always in group 0 regardless of
keyboard state.</p>
<p>Note that <a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-translate-keyboard-state" title="gdk_keymap_translate_keyboard_state ()"><code class="function">gdk_keymap_translate_keyboard_state()</code></a> 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. <span class="type">GdkEventKey</span> already
effective group/level values were used for the lookup. <a class="link" href="gdk3-Event-Structures.html#GdkEventKey" title="struct GdkEventKey"><span class="type">GdkEventKey</span></a> already
contains this keyval, however, so you don’t normally need to call
<a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-translate-keyboard-state" title="gdk_keymap_translate_keyboard_state ()"><code class="function">gdk_keymap_translate_keyboard_state()</code></a> just to get the keyval.</p>
</div>
@ -404,7 +404,7 @@ gdk_keymap_get_for_display (<em class="parameter"><code><a class="link" href="Gd
<a name="gdk-keymap-lookup-key"></a><h3>gdk_keymap_lookup_key ()</h3>
<pre class="programlisting"><span class="returnvalue">guint</span>
gdk_keymap_lookup_key (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code>const <span class="type">GdkKeymapKey</span> *key</code></em>);</pre>
<em class="parameter"><code>const <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> *key</code></em>);</pre>
<p>Looks up the keyval mapped to a keycode/group/level triplet.
If no keyval is bound to <em class="parameter"><code>key</code></em>
, returns 0. For normal user input,
@ -427,7 +427,7 @@ the same as the current keyboard state.</p>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description"><p>a <span class="type">GdkKeymapKey</span> with keycode, group, and level initialized</p></td>
<td class="parameter_description"><p>a <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> with keycode, group, and level initialized</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
@ -445,13 +445,13 @@ the same as the current keyboard state.</p>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
gdk_keymap_translate_keyboard_state (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">guint</span> hardware_keycode</code></em>,
<em class="parameter"><code><span class="type">GdkModifierType</span> state</code></em>,
<em class="parameter"><code><a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="type">GdkModifierType</span></a> state</code></em>,
<em class="parameter"><code><span class="type">gint</span> group</code></em>,
<em class="parameter"><code><span class="type">guint</span> *keyval</code></em>,
<em class="parameter"><code><span class="type">gint</span> *effective_group</code></em>,
<em class="parameter"><code><span class="type">gint</span> *level</code></em>,
<em class="parameter"><code><span class="type">GdkModifierType</span> *consumed_modifiers</code></em>);</pre>
<p>Translates the contents of a <span class="type">GdkEventKey</span> into a keyval, effective
<em class="parameter"><code><a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="type">GdkModifierType</span></a> *consumed_modifiers</code></em>);</pre>
<p>Translates the contents of a <a class="link" href="gdk3-Event-Structures.html#GdkEventKey" title="struct GdkEventKey"><span class="type">GdkEventKey</span></a> into a keyval, effective
group, and level. Modifiers that affected the translation and
are thus unavailable for application use are returned in
<em class="parameter"><code>consumed_modifiers</code></em>
@ -463,7 +463,7 @@ actually used for the translation; some keys such as Enter are not
affected by the active keyboard group. The <em class="parameter"><code>level</code></em>
is derived from
<em class="parameter"><code>state</code></em>
. For convenience, <span class="type">GdkEventKey</span> already contains the translated
. For convenience, <a class="link" href="gdk3-Event-Structures.html#GdkEventKey" title="struct GdkEventKey"><span class="type">GdkEventKey</span></a> already contains the translated
keyval, so this function isn’t as useful as you might think.</p>
<p><em class="parameter"><code>consumed_modifiers</code></em>
gives modifiers that should be masked outfrom <em class="parameter"><code>state</code></em>
@ -596,7 +596,7 @@ that were used to determine the group or level, or <code class="literal">NULL</c
<pre class="programlisting"><span class="returnvalue">gboolean</span>
gdk_keymap_get_entries_for_keyval (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">guint</span> keyval</code></em>,
<em class="parameter"><code><span class="type">GdkKeymapKey</span> **keys</code></em>,
<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> **keys</code></em>,
<em class="parameter"><code><span class="type">gint</span> *n_keys</code></em>);</pre>
<p>Obtains a list of keycode/group/level combinations that will
generate <em class="parameter"><code>keyval</code></em>
@ -606,7 +606,7 @@ 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.
<span class="type">GdkEventKey</span> contains a <code class="literal">group</code> field that indicates the active
<a class="link" href="gdk3-Event-Structures.html#GdkEventKey" title="struct GdkEventKey"><span class="type">GdkEventKey</span></a> contains a <code class="literal">group</code> field that indicates the active
keyboard group. The level is computed from the modifier mask.
The returned array should be freed
with <code class="function">g_free()</code>.</p>
@ -632,7 +632,7 @@ with <code class="function">g_free()</code>.</p>
<tr>
<td class="parameter_name"><p>keys</p></td>
<td class="parameter_description"><p>return location
for an array of <span class="type">GdkKeymapKey</span>. </p></td>
for an array of <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_keys][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td>
</tr>
<tr>
@ -654,12 +654,12 @@ for an array of <span class="type">GdkKeymapKey</span>. </p></td>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
gdk_keymap_get_entries_for_keycode (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">guint</span> hardware_keycode</code></em>,
<em class="parameter"><code><span class="type">GdkKeymapKey</span> **keys</code></em>,
<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> **keys</code></em>,
<em class="parameter"><code><span class="type">guint</span> **keyvals</code></em>,
<em class="parameter"><code><span class="type">gint</span> *n_entries</code></em>);</pre>
<p>Returns the keyvals bound to <em class="parameter"><code>hardware_keycode</code></em>
.
The Nth <span class="type">GdkKeymapKey</span> in <em class="parameter"><code>keys</code></em>
The Nth <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> in <em class="parameter"><code>keys</code></em>
is bound to the Nth
keyval in <em class="parameter"><code>keyvals</code></em>
. Free the returned arrays with <code class="function">g_free()</code>.
@ -688,7 +688,7 @@ keyboard group and level. See <a class="link" href="gdk3-Keyboard-Handling.html#
<tr>
<td class="parameter_name"><p>keys</p></td>
<td class="parameter_description"><p>return
location for array of <span class="type">GdkKeymapKey</span>, or <code class="literal">NULL</code>. </p></td>
location for array of <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a>, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_entries][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>]</span></td>
</tr>
<tr>
@ -881,7 +881,7 @@ gdk_keymap_get_modifier_state (<em class="parameter"><code><a class="link" href=
<a name="gdk-keymap-add-virtual-modifiers"></a><h3>gdk_keymap_add_virtual_modifiers ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gdk_keymap_add_virtual_modifiers (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">GdkModifierType</span> *state</code></em>);</pre>
<em class="parameter"><code><a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="type">GdkModifierType</span></a> *state</code></em>);</pre>
<p>Maps the non-virtual modifiers (i.e Mod2, Mod3, ...) which are set
in <em class="parameter"><code>state</code></em>
to the virtual modifiers (i.e. Super, Hyper and Meta) and
@ -921,7 +921,7 @@ accelerators.</p>
<a name="gdk-keymap-map-virtual-modifiers"></a><h3>gdk_keymap_map_virtual_modifiers ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
gdk_keymap_map_virtual_modifiers (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">GdkModifierType</span> *state</code></em>);</pre>
<em class="parameter"><code><a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="type">GdkModifierType</span></a> *state</code></em>);</pre>
<p>Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
are set in <em class="parameter"><code>state</code></em>
to their non-virtual counterparts (i.e. Mod2,
@ -964,15 +964,15 @@ was already set in <em class="parameter"><code>state</code></em>
<hr>
<div class="refsect2">
<a name="gdk-keymap-get-modifier-mask"></a><h3>gdk_keymap_get_modifier_mask ()</h3>
<pre class="programlisting"><span class="returnvalue">GdkModifierType</span>
<pre class="programlisting"><a class="link" href="gdk3-Windows.html#GdkModifierType" title="enum GdkModifierType"><span class="returnvalue">GdkModifierType</span></a>
gdk_keymap_get_modifier_mask (<em class="parameter"><code><a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> *keymap</code></em>,
<em class="parameter"><code><span class="type">GdkModifierIntent</span> intent</code></em>);</pre>
<em class="parameter"><code><a class="link" href="gdk3-Windows.html#GdkModifierIntent" title="enum GdkModifierIntent"><span class="type">GdkModifierIntent</span></a> intent</code></em>);</pre>
<p>Returns the modifier mask the <em class="parameter"><code>keymap</code></em>
’s windowing system backend
uses for a particular purpose.</p>
<p>Note that this function always returns real hardware modifiers, not
virtual ones (e.g. it will return <span class="type">GDK_MOD1_MASK</span> rather than
<span class="type">GDK_META_MASK</span> if the backend maps MOD1 to META), so there are use
virtual ones (e.g. it will return <a class="link" href="gdk3-Windows.html#GDK-MOD1-MASK:CAPS"><span class="type">GDK_MOD1_MASK</span></a> rather than
<a class="link" href="gdk3-Windows.html#GDK-META-MASK:CAPS"><span class="type">GDK_META_MASK</span></a> if the backend maps MOD1 to META), so there are use
cases where the return value of this function has to be transformed
by <a class="link" href="gdk3-Keyboard-Handling.html#gdk-keymap-add-virtual-modifiers" title="gdk_keymap_add_virtual_modifiers ()"><code class="function">gdk_keymap_add_virtual_modifiers()</code></a> in order to contain the
expected result.</p>
@ -1282,6 +1282,66 @@ wc | 0x01000000</p>
</div>
</div>
<div class="refsect1">
<a name="gdk3-Keyboard-Handling.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GdkKeymap-struct"></a><h3>GdkKeymap</h3>
<pre class="programlisting">typedef struct _GdkKeymap GdkKeymap;</pre>
<p>A <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymap"><span class="type">GdkKeymap</span></a> 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.</p>
</div>
<hr>
<div class="refsect2">
<a name="GdkKeymapKey"></a><h3>struct GdkKeymapKey</h3>
<pre class="programlisting">struct GdkKeymapKey {
guint keycode;
gint group;
gint level;
};
</pre>
<p>A <a class="link" href="gdk3-Keyboard-Handling.html#GdkKeymapKey" title="struct GdkKeymapKey"><span class="type">GdkKeymapKey</span></a> is a hardware key that can be mapped to a keyval.</p>
<div class="refsect3">
<a name="GdkKeymapKey.members"></a><h4>Members</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="300px" class="struct_members_name">
<col class="struct_members_description">
<col width="200px" class="struct_members_annotations">
</colgroup>
<tbody>
<tr>
<td class="struct_member_name"><p><span class="type">guint</span> <em class="structfield"><code><a name="GdkKeymapKey.keycode"></a>keycode</code></em>;</p></td>
<td class="struct_member_description"><p>the hardware keycode. This is an identifying number for a
physical key.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><span class="type">gint</span> <em class="structfield"><code><a name="GdkKeymapKey.group"></a>group</code></em>;</p></td>
<td class="struct_member_description"><p>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.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><span class="type">gint</span> <em class="structfield"><code><a name="GdkKeymapKey.level"></a>level</code></em>;</p></td>
<td class="struct_member_description"><p>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.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
<div class="refsect1">
<a name="gdk3-Keyboard-Handling.signal-details"></a><h2>Signal Details</h2>
<div class="refsect2">
<a name="GdkKeymap-direction-changed"></a><h3>The <code class="literal">“direction-changed”</code> signal</h3>