gtk+ r21946 - in trunk/docs/reference: . gtk

[matthiasc svn gnome org]

Author: matthiasc
Date: Sat Dec 27 05:59:42 2008
New Revision: 21946
URL: http://svn.gnome.org/viewvc/gtk+?rev=21946&view=rev

Log:
Add new migration chapter


Added:
   trunk/docs/reference/gtk/migrating-GtkEntry-icons.sgml
Modified:
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/gtk/gtk-docs.sgml

Modified: trunk/docs/reference/gtk/gtk-docs.sgml
==============================================================================
--- trunk/docs/reference/gtk/gtk-docs.sgml	(original)
+++ trunk/docs/reference/gtk/gtk-docs.sgml	Sat Dec 27 05:59:42 2008
@@ -425,6 +425,7 @@
     <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>

Added: trunk/docs/reference/gtk/migrating-GtkEntry-icons.sgml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/gtk/migrating-GtkEntry-icons.sgml	Sat Dec 27 05:59:42 2008
@@ -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>