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

<?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>
    The signals SexyIconEntry::icon-pressed and SexyIconEntry::icon-released
    have been renamed to #GtkEntry::icon-press and #GtkEntry::icon-release
    to avoid problems due to signal name clashes. Also, the signature of the
    signals has changed from
<informalexample><programlisting>
void (*icon_pressed) (SexyIconEntry         *entry, 
                      SexyIconEntryPosition  icon_pos,
                      int                    button)
</programlisting></informalexample>
to
<informalexample><programlisting>
void (*icon_press) (GtkEntry              *entry, 
                    GtkEntryIconPosition  icon_pos,
                    GdkEventButton       *event)
</programlisting></informalexample>
    The new signature has the advantage that the signal handler can use
    the timestamp of the event, e.g. for passing it to gtk_menu_popup().
    When adapting an existing signal handler to the new signature, you 
    should note that the button number is easily available as @event->button,
    as shown in the following example:
<informalexample><programlisting>
static void
icon_pressed_cb (SexyIconEntry         *entry,
                 SexyIconEntryPosition  position,
                 int                    button,
                 gpointer               data)
{
  GtkMenu *menu = data;

  if (position == SEXY_ICON_ENTRY_PRIMARY)
    gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
                    button, GDK_CURRENT_TIME);
} 
</programlisting></informalexample>
    can be ported as:
<informalexample><programlisting>
static void
icon_press_cb (GtkEntry             *entry,
               GtkEntryIconPosition  position,
               GdkEventButton       *event,
               gpointer              data)
{
  GtkMenu *menu = data;

  if (position == GTK_ENTRY_ICON_PRIMARY)
    gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
                    event->button, event->time);
} 
</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:
    <itemizedlist>
      <listitem><para>
        Sensitive, but non-activatable icons are
        good for purely informational purposes.
      </para></listitem>
      <listitem><para>
        Icons should be marked as insensitive if the
        function that they trigger is currently not available.
      </para></listitem>
    </itemizedlist>
  </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>