Note that a widget must be focusable for the menu keybindings to work.

2004-01-23  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-checklist.sgml: Note that a widget must be
	focusable for the menu keybindings to work.

2004-01-22  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-checklist.sgml: Mention when it is useful to use
	GdkEventExpose.region rather than GdkEventExpose.area.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e9c1b8ff72ffc45994f06875dda0fab62ab07a89..9f467aa7ed51f9e08d1db471cf48c26f11948014 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,13 @@
+2004-01-23  Federico Mena Quintero  <federico@ximian.com>
+
+       * gtk/migrating-checklist.sgml: Note that a widget must be
+       focusable for the menu keybindings to work.
+
+2004-01-22  Federico Mena Quintero  <federico@ximian.com>
+
+       * gtk/migrating-checklist.sgml: Mention when it is useful to use
+       GdkEventExpose.region rather than GdkEventExpose.area.
+
 2004-01-22  Federico Mena Quintero  <federico@ximian.com>
 
        * gtk/migrating-checklist.sgml: Point to GtkEntry as an example of

diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml
index fb6b167c38a9c0ace2e62f0823e7905eae15c74e..08eba65c8b9ccc8d1620ff1e3871fbe118a42e2e 100644 (file)
--- a/docs/reference/gtk/migrating-checklist.sgml
+++ b/docs/reference/gtk/migrating-checklist.sgml
@@ -131,6 +131,84 @@ my_widget_popup_menu_handler (GtkWidget *widget)
        top edge of its popup menu with the bottom edge of the entry.
       </para>
     </note>
+
+    <note>
+      <para>
+       For the standard key bindings to work, your widget must be
+       able to take the keyboard focus.  In general, widgets should
+       be fully usable through the keyboard and not just the mouse.
+       The very first step of this is to ensure that your widget
+       turns on the <link
+       linkend="gtkwidgetflags"><constant>GTK_CAN_FOCUS</constant></link>
+       FLAG.
+      </para>
+    </note>
+  </section>
+
+  <section id="checklist-gdkeventexpose-region">
+    <title>Use GdkEventExpose.region</title>
+
+    <formalpara>
+      <title>Why</title>
+      <para>
+       The <structfield>region</structfield> field of
+       <structname>GdkEventExpose</structname> allows you to redraw
+       less than the traditional
+       <structfield>GdkEventRegion.area</structfield>.
+      </para>
+    </formalpara>
+
+    <para>
+      In GTK+ 1.x, the <structname>GdkEventExpose</structname>
+      structure only had an <structfield>area</structfield> field to
+      let you determine the region that you needed to redraw.  In GTK+
+      2.x, this field exists for compatibility and as a simple
+      interface.  However, there is also a
+      <structfield>region</structfield> field which contains a
+      fine-grained region.  The <structfield>area</structfield> field
+      is simply the bounding rectangle of the
+      <structfield>region</structfield>.
+    </para>
+
+    <para>
+      Widgets that are very expensive to re-render, such as an image
+      editor, may prefer to use the
+      <structfield>GdkEventExpose.region</structfield> field to paint
+      as little as possible.  Widgets that just use a few drawing
+      primitives, such as labels and buttons, may prefer to use the
+      traditional <structfield>GdkEventExpose.area</structfield> field
+      for simplicity.
+    </para>
+
+    <para>
+      Regions have an internal representation that is accessible as a
+      list of rectangles.  To turn the
+      <structfield>GdkEventExpose.region</structfield> field into such
+      a list, use gdk_region_get_rectangles():
+    </para>
+
+    <programlisting id="gdkregion-get-rectangles">
+static gboolean
+my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
+{
+  GdkRectangle *rects;
+  int n_rects;
+  int i;
+
+  gdk_region_get_rectangles (event-&gt;region, &amp;rects, &amp;n_rects);
+
+  for (i = 0; i &lt; n_rects; i++)
+    {
+      /* Repaint rectangle: (rects[i].x, rects[i].y), 
+       *                    (rects[i].width, rects[i].height)
+       */
+    }
+
+  g_free (rects);
+
+  return FALSE;
+}
+    </programlisting>
   </section>
 </chapter>