diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/reference/ChangeLog | 2 | ||||
-rw-r--r-- | docs/reference/gtk/migrating-checklist.sgml | 48 |
2 files changed, 50 insertions, 0 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 9478a875e..a049d527a 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -3,6 +3,8 @@ * gdk/tmpl/windows.sgml: Added an example of how to use GDK_MODIFIER_MASK to test for modifier keys correctly. + * gtk/migrating-checklist.sgml: Likewise. + Sun Feb 15 23:51:08 2004 Matthias Clasen <maclas@gmx.de> * gtk/tmpl/gtkcomboboxentry.sgml: diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml index 08eba65c8..9c83a7030 100644 --- a/docs/reference/gtk/migrating-checklist.sgml +++ b/docs/reference/gtk/migrating-checklist.sgml @@ -210,6 +210,54 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) } </programlisting> </section> + + <section id="checklist-modifiers"> + <title>Test for modifier keys correctly</title> + + <formalpara> + <title>Why</title> + <para> + With <constant>GDK_MODIFIER_MASK</constant> you can test for + modifier keys reliably; this way your key event handlers will + work correctly even if <keycap>NumLock</keycap> or + <keycap>CapsLock</keycap> are activated. + </para> + </formalpara> + + <para> + In a <structname>GdkEventKey</structname>, the + <structfield>state</structfield> field is a bit mask which + indicates the modifier state at the time the key was pressed. + Modifiers are keys like <keycap>Control</keycap>, and + <keycap>NumLock</keycap>. When implementing a <link + linkend="GtkWidget-key-press-event">GtkWidget::key_press_event</link> + handler, you should use the + <constant>GDK_MODIFIER_MASK</constant> constant to test against + modifier keys. This value encompasses all the modifiers which + the user may be actively pressing, such as + <keycap>Control</keycap> and <keycap>Shift</keycap>, but ignores + "inocuous" modifiers such as <keycap>NumLock</keycap> and + <keycap>CapsLock</keycap>. The following example tests for + <keycombo> + <keycap>Control</keycap><keycap>F10</keycap></keycombo> being + pressed. + </para> + + <programlisting id="GDK_MODIFIER_MASK"> +static gboolean +my_widget_key_press_handler (GtkWidget *widget, GdkEventKey *event) +{ + if (event->keysym == GDK_F10 + && (event->state & GDK_MODIFIER_MASK) == GDK_CONTROL_MASK) + { + g_print ("Control-F10 was pressed\n"); + return TRUE; + } + + return FALSE; +} + </programlisting> + </section> </chapter> <!-- |