Add new migration chapter

svn path=/trunk/; revision=21946

docs/reference/ChangeLog

@@ -1,6 +1,8 @@
 2008-12-27  Matthias Clasen <mclasen@redhat.com>
 
 	* gtk/migrating-GtkLinkButton.sgml: Mention default hook
+	* gtk/migrating-GtkEntry-icons.sgml: Migration chapter 
+	SexyIconEntry -> GtkEntry
 
 2008-12-27  Matthias Clasen <mclasen@redhat.com>
 

docs/reference/gtk/gtk-docs.sgml

@@ -425,6 +425,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <xi:include href="xml/migrating-GtkLinkButton.sgml" />
     <xi:include href="xml/migrating-GtkBuilder.sgml" />
     <xi:include href="xml/migrating-GtkTooltip.sgml" />
+    <xi:include href="xml/migrating-GtkEntry-icons.sgml" />
   </part>
 
   <part>

docs/reference/gtk/migrating-GtkEntry-icons.sgml

@@ -0,0 +1,88 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="gtk-migrating-entry-icons">
+
+  <title>Migrating from SexyIconEntry to GtkEntry</title>
+
+  <para>
+    GTK+ 2.16 supports showing icons inside a #GtkEntry, similar to 
+    SexyIconEntry. Porting from SexyIconEntry to GtkEntry is relatively 
+    straightforward. The main difference between the two APIs is that 
+    SexyIconEntry uses #GtkImage widgets in a somewhat awkward way as 
+    storage vehicles for icons, while GtkEntry allows to specify icons
+    via pixbufs, stock ids, icon names or #GIcons. So, if your code uses
+    e.g.:
+<informalexample><programlisting>
+image = gtk_image_new_from_stock (GTK_STOCK_NEW, GTK_ICON_SIZE_MENU);
+sexy_icon_entry_set_icon (entry, SEXY_ICON_ENTRY_PRIMARY, image);
+</programlisting></informalexample>
+    you can get rid of the @image, and directly write:
+<informalexample><programlisting>
+gtk_entry_set_icon_from_stock (entry, GTK_ICON_ENTRY_PRIMARY, GTK_STOCK_NEW);
+</programlisting></informalexample>
+  </para>
+
+  <para>
+    Another difference is that SexyIconEntry offers manual control of
+    the icon prelighting, via sexy_icon_entry_set_icon_highlight(). 
+    #GtkEntry prelights automatically when appropriate, depending on 
+    whether the icon is activatable and sensitive. You should make
+    sure that your icons are properly marked as activatable or nonactivatable
+    and sensitive or insensitive:
+    <varlist>
+      <varlistentry>
+        <listitem><para>Sensitive, but non-activatable icons are
+        good for purely informational purposes.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <listitem><para>Icons should be marked as insensitive if the
+        function that they trigger is currently not available.</para></listitem>
+      </varlistentry>
+  </para>
+
+  <para>
+    GtkEntry has no direct equivalent of the special-purpose function
+    sexy_icon_entry_add_clear_button(). If you need this functionality,
+    the following code works:
+<informalexample><programlisting>
+static void
+icon_pressed_cb (GtkEntry       *entry,
+                 gint            position,
+                 GdkEventButton *event,
+                 gpointer        data)
+{
+  if (position == GTK_ENTRY_ICON_SECONDARY)
+    gtk_entry_set_text (entry, "");
+}
+
+static void
+text_changed_cb (GtkEntry   *entry,
+                 GParamSpec *pspec,
+                 GtkWidget  *button)
+{
+  gboolean has_text;
+
+  has_text = gtk_entry_get_text_length (entry) > 0;
+  gtk_entry_set_icon_sensitive (entry,
+                                GTK_ENTRY_ICON_SECONDARY,
+                                has_text);
+}
+
+
+  /* ... */
+ 
+  /* Set up the clear icon */
+  gtk_entry_set_icon_from_stock (GTK_ENTRY (entry),
+                                 GTK_ENTRY_ICON_SECONDARY,
+                                 GTK_STOCK_CLEAR);
+  g_signal_connect (entry, "icon-pressed",
+                    G_CALLBACK (icon_pressed_cb), NULL);
+  g_signal_connect (entry, "notify::text",
+                    G_CALLBACK (text_changed_cb), find_button);
+ 
+  /* ... */
+</programlisting></informalexample>
+  </para>
+</chapter>