Umm, I'm on crack. Use gtk_accelerator_get_default_mod_mask().

2004-02-16  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-checklist.sgml: Umm, I'm on crack.  Use
	gtk_accelerator_get_default_mod_mask().

	* gdk/tmpl/windows.sgml: Removed the incorrect description from
	GDK_MODIFIER_MASK.

docs/reference/ChangeLog

@@ -1,3 +1,11 @@
+2004-02-16  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/migrating-checklist.sgml: Umm, I'm on crack.  Use
+	gtk_accelerator_get_default_mod_mask().
+
+	* gdk/tmpl/windows.sgml: Removed the incorrect description from
+	GDK_MODIFIER_MASK.
+
 2004-02-16  Federico Mena Quintero  <federico@ximian.com>
 
 	* gdk/tmpl/windows.sgml: Added an example of how to use

docs/reference/gdk/tmpl/windows.sgml

@@ -1126,38 +1126,7 @@ Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.
 @GDK_BUTTON5_MASK: the fifth mouse button.
 @GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate 
   between (keyval, modifiers) pairs from key press and release events.
-@GDK_MODIFIER_MASK: Mask that can be used to see if modifier keys are
+@GDK_MODIFIER_MASK: 
-  pressed.  See <xref linkend="keys-with-modifiers"/> for an example
-  of how to use this mask.
-
-  <example id="keys-with-modifiers">
-    <title>Testing for keys with modifiers</title>
-
-    <para>
-      The following code shows how you should use GDK_MODIFIER_MASK to
-      test for
-      <keycombo><keycap>Control</keycap><keycap>F10</keycap></keycombo>
-      being pressed.  If you do something like testing for
-      <literal>event-&gt;state == GDK_CONTROL_MASK</literal>, your
-      program will not work correctly if some other modifier is
-      pressed, such as <keycap>NumLock</keycap>.
-    </para>
-
-    <programlisting>
-static gboolean
-my_widget_key_press_handler (GtkWidget *widget, GdkEventKey *event)
-{
-  if (event-&gt;keysym == GDK_F10
-      &amp;&amp; (event-&gt;state &amp; GDK_MODIFIER_MASK) == GDK_CONTROL_MASK)
-    {
-      g_print ("Control-F10 was pressed\n");
-      return TRUE;
-    }
-
-  return FALSE;
-}
-    </programlisting>
-  </example>
 
 <!-- ##### FUNCTION gdk_window_get_parent ##### -->
 <para>

docs/reference/gtk/migrating-checklist.sgml

@@ -217,10 +217,12 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
     <formalpara>
       <title>Why</title>
       <para>
-	With <constant>GDK_MODIFIER_MASK</constant> you can test for
+	With
-	modifier keys reliably; this way your key event handlers will
+	<function>gtk_accelerator_get_default_mod_mask()</function>
-	work correctly even if <keycap>NumLock</keycap> or
+	you can test for modifier keys reliably; this way your key
-	<keycap>CapsLock</keycap> are activated.
+	event handlers will work correctly even if
+	<keycap>NumLock</keycap> or <keycap>CapsLock</keycap> are
+	activated.
       </para>
     </formalpara>
 
@@ -228,27 +230,51 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
       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
+      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
+      handler, you should use
-      <constant>GDK_MODIFIER_MASK</constant> constant to test against
+      <function>gtk_accelerator_get_default_mod_mask()</function> to
-      modifier keys.  This value encompasses all the modifiers which
+      test against modifier keys.  This function returns a bit mask
-      the user may be actively pressing, such as
+      which encompasses all the modifiers which the user may be
-      <keycap>Control</keycap> and <keycap>Shift</keycap>, but ignores
+      actively pressing, such as <keycap>Control</keycap>,
+      <keycap>Shift</keycap>, and <keycap>Alt</keycap>, but ignores
       "inocuous" modifiers such as <keycap>NumLock</keycap> and
-      <keycap>CapsLock</keycap>.  The following example tests for
+      <keycap>CapsLock</keycap>.
-      <keycombo>
-      <keycap>Control</keycap><keycap>F10</keycap></keycombo> being
-      pressed.
     </para>
 
-    <programlisting id="GDK_MODIFIER_MASK">
+    <para>
+      Say you want to see if
+      <keycombo><keycap>Control</keycap><keycap>F10</keycap></keycombo>
+      was pressed.  Doing a simple test like
+      <literal>event-&gt;keysym&nbsp;==&nbspGDK_F10 &amp;&amp;
+      event->state&nbsp;==&nbsp;GDK_CONTROL_MASK</literal> is not
+      enough.  If <keycap>CapsLock</keycap> is pressed, then
+      <structfield>event-&gt;state</structfield> will be equal to
+      <literal>GDK_CONTROL_MASK | GDK_LOCK_MASK</literal>, and the
+      simple test will fail.  By taking the logical-and of
+      <structfield>event->state</structfield> and
+      <function>gtk_accelerator_get_default_mod_mask()</function>, you
+      can ignore the modifiers which are not actively pressed by the
+      user at the same time as the base key.
+    </para>
+
+    <para>
+      The following example correctly tests for
+      <keycombo><keycap>Control</keycap><keycap>F10</keycap></keycombo>
+      being pressed.
+    </para>
+
+    <programlisting id="default-mod-mask">
 static gboolean
-my_widget_key_press_handler (GtkWidget *widget, GdkEventKey *event)
+my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event)
 {
+  guint modifiers;
+
+  modifiers = gtk_accelerator_get_default_mod_mask ();
+
   if (event-&gt;keysym == GDK_F10
-      &amp;&amp; (event-&gt;state &amp; GDK_MODIFIER_MASK) == GDK_CONTROL_MASK)
+      &amp;&amp; (event-&gt;state &amp; modifiers) == GDK_CONTROL_MASK)
     {
       g_print ("Control-F10 was pressed\n");
       return TRUE;