Pileus Git - ~andy/gtk/blob - docs/reference/gtk/migrating-GtkEntry-icons.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <chapter id="gtk-migrating-entry-icons">
   6
   7   <title>Migrating from SexyIconEntry to GtkEntry</title>
   8
   9   <para>
  10     GTK+ 2.16 supports showing icons inside a #GtkEntry, similar to
  11     SexyIconEntry. Porting from SexyIconEntry to GtkEntry is relatively
  12     straightforward. The main difference between the two APIs is that
  13     SexyIconEntry uses #GtkImage widgets in a somewhat awkward way as
  14     storage vehicles for icons, while GtkEntry allows to specify icons
  15     via pixbufs, stock ids, icon names or #GIcons. So, if your code uses
  16     e.g.:
  17 <informalexample><programlisting>
  18 image = gtk_image_new_from_stock (GTK_STOCK_NEW, GTK_ICON_SIZE_MENU);
  19 sexy_icon_entry_set_icon (entry, SEXY_ICON_ENTRY_PRIMARY, image);
  20 </programlisting></informalexample>
  21     you can get rid of the @image, and directly write:
  22 <informalexample><programlisting>
  23 gtk_entry_set_icon_from_stock (entry, GTK_ICON_ENTRY_PRIMARY, GTK_STOCK_NEW);
  24 </programlisting></informalexample>
  25   </para>
  26
  27   <para>
  28     Another difference is that SexyIconEntry offers manual control of
  29     the icon prelighting, via sexy_icon_entry_set_icon_highlight().
  30     #GtkEntry prelights automatically when appropriate, depending on
  31     whether the icon is activatable and sensitive. You should make
  32     sure that your icons are properly marked as activatable or nonactivatable
  33     and sensitive or insensitive:
  34     <itemizedlist>
  35       <listitem><para>
  36         Sensitive, but non-activatable icons are
  37         good for purely informational purposes.
  38       </para></listitem>
  39       <listitem><para>
  40         Icons should be marked as insensitive if the
  41         function that they trigger is currently not available.
  42       </para></listitem>
  43     </itemizedlist>
  44   </para>
  45
  46   <para>
  47     GtkEntry has no direct equivalent of the special-purpose function
  48     sexy_icon_entry_add_clear_button(). If you need this functionality,
  49     the following code works:
  50 <informalexample><programlisting>
  51 static void
  52 icon_pressed_cb (GtkEntry       *entry,
  53                  gint            position,
  54                  GdkEventButton *event,
  55                  gpointer        data)
  56 {
  57   if (position == GTK_ENTRY_ICON_SECONDARY)
  58     gtk_entry_set_text (entry, "");
  59 }
  60
  61 static void
  62 text_changed_cb (GtkEntry   *entry,
  63                  GParamSpec *pspec,
  64                  GtkWidget  *button)
  65 {
  66   gboolean has_text;
  67
  68   has_text = gtk_entry_get_text_length (entry) > 0;
  69   gtk_entry_set_icon_sensitive (entry,
  70                                 GTK_ENTRY_ICON_SECONDARY,
  71                                 has_text);
  72 }
  73
  74
  75   /* ... */
  76
  77   /* Set up the clear icon */
  78   gtk_entry_set_icon_from_stock (GTK_ENTRY (entry),
  79                                  GTK_ENTRY_ICON_SECONDARY,
  80                                  GTK_STOCK_CLEAR);
  81   g_signal_connect (entry, "icon-pressed",
  82                     G_CALLBACK (icon_pressed_cb), NULL);
  83   g_signal_connect (entry, "notify::text",
  84                     G_CALLBACK (text_changed_cb), find_button);
  85
  86   /* ... */
  87 </programlisting></informalexample>
  88   </para>
  89 </chapter>