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_ENTRY_ICON_PRIMARY, GTK_STOCK_NEW);
  24 </programlisting></informalexample>
  25   </para>
  26
  27   <para>
  28     The signals SexyIconEntry::icon-pressed and SexyIconEntry::icon-released
  29     have been renamed to #GtkEntry::icon-press and #GtkEntry::icon-release
  30     to avoid problems due to signal name clashes. Also, the signature of the
  31     signals has changed from
  32 <informalexample><programlisting>
  33 void (*icon_pressed) (SexyIconEntry         *entry,
  34                       SexyIconEntryPosition  icon_pos,
  35                       int                    button)
  36 </programlisting></informalexample>
  37 to
  38 <informalexample><programlisting>
  39 void (*icon_press) (GtkEntry              *entry,
  40                     GtkEntryIconPosition  icon_pos,
  41                     GdkEventButton       *event)
  42 </programlisting></informalexample>
  43     The new signature has the advantage that the signal handler can use
  44     the timestamp of the event, e.g. for passing it to gtk_menu_popup().
  45     When adapting an existing signal handler to the new signature, you
  46     should note that the button number is easily available as @event->button,
  47     as shown in the following example:
  48 <informalexample><programlisting>
  49 static void
  50 icon_pressed_cb (SexyIconEntry         *entry,
  51                  SexyIconEntryPosition  position,
  52                  int                    button,
  53                  gpointer               data)
  54 {
  55   GtkMenu *menu = data;
  56
  57   if (position == SEXY_ICON_ENTRY_PRIMARY)
  58     gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
  59                     button, GDK_CURRENT_TIME);
  60 }
  61 </programlisting></informalexample>
  62     can be ported as:
  63 <informalexample><programlisting>
  64 static void
  65 icon_press_cb (GtkEntry             *entry,
  66                GtkEntryIconPosition  position,
  67                GdkEventButton       *event,
  68                gpointer              data)
  69 {
  70   GtkMenu *menu = data;
  71
  72   if (position == GTK_ENTRY_ICON_PRIMARY)
  73     gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
  74                     event->button, event->time);
  75 }
  76 </programlisting></informalexample>
  77   </para>
  78
  79   <para>
  80     Another difference is that SexyIconEntry offers manual control of
  81     the icon prelighting, via sexy_icon_entry_set_icon_highlight().
  82     #GtkEntry prelights automatically when appropriate, depending on
  83     whether the icon is activatable and sensitive. You should make
  84     sure that your icons are properly marked as activatable or nonactivatable
  85     and sensitive or insensitive:
  86     <itemizedlist>
  87       <listitem><para>
  88         Sensitive, but non-activatable icons are
  89         good for purely informational purposes.
  90       </para></listitem>
  91       <listitem><para>
  92         Icons should be marked as insensitive if the
  93         function that they trigger is currently not available.
  94       </para></listitem>
  95     </itemizedlist>
  96   </para>
  97
  98   <para>
  99     GtkEntry has no direct equivalent of the special-purpose function
 100     sexy_icon_entry_add_clear_button(). If you need this functionality,
 101     the following code works:
 102 <informalexample><programlisting>
 103 static void
 104 icon_pressed_cb (GtkEntry       *entry,
 105                  gint            position,
 106                  GdkEventButton *event,
 107                  gpointer        data)
 108 {
 109   if (position == GTK_ENTRY_ICON_SECONDARY)
 110     gtk_entry_set_text (entry, "");
 111 }
 112
 113 static void
 114 text_changed_cb (GtkEntry   *entry,
 115                  GParamSpec *pspec,
 116                  GtkWidget  *button)
 117 {
 118   gboolean has_text;
 119
 120   has_text = gtk_entry_get_text_length (entry) > 0;
 121   gtk_entry_set_icon_sensitive (entry,
 122                                 GTK_ENTRY_ICON_SECONDARY,
 123                                 has_text);
 124 }
 125
 126
 127   /* ... */
 128
 129   /* Set up the clear icon */
 130   gtk_entry_set_icon_from_stock (GTK_ENTRY (entry),
 131                                  GTK_ENTRY_ICON_SECONDARY,
 132                                  GTK_STOCK_CLEAR);
 133   g_signal_connect (entry, "icon-pressed",
 134                     G_CALLBACK (icon_pressed_cb), NULL);
 135   g_signal_connect (entry, "notify::text",
 136                     G_CALLBACK (text_changed_cb), find_button);
 137
 138   /* ... */
 139 </programlisting></informalexample>
 140   </para>
 141 </chapter>