File: migrating-GtkEntry-icons.sgml

package info (click to toggle)
gtk%2B2.0 2.24.33-7
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie, trixie-proposed-updates, trixie-updates
  • size: 124,860 kB
  • sloc: ansic: 574,091; makefile: 5,171; sh: 4,618; xml: 1,193; python: 1,117; perl: 749; awk: 49; cpp: 34
file content (141 lines) | stat: -rw-r--r-- 5,164 bytes parent folder | download | duplicates (10)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
<?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_ENTRY_ICON_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-press",
                    G_CALLBACK (icon_pressed_cb), NULL);
  g_signal_connect (entry, "notify::text",
                    G_CALLBACK (text_changed_cb), find_button);
 
  /* ... */
</programlisting></informalexample>
  </para>
</chapter>