Rename GtkEntry icon-related signals

svn path=/trunk/; revision=22023

3 files changed, 63 insertions, 4 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 764e545eb9..1ca92a597e 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2008-12-31  Matthias Clasen <mclasen@redhat.com>
+
+	* gtk/migrating-GtkEntry-icons.sgml: Add a section about
+	signals.
+
+	* gtk/tmpl/gtkentry.sgml: Update to new signal names
+
 2008-12-30  Matthias Clasen <mclasen@redhat.com>
 
 	* gtk/tmpl/gtkorientable.sgml:
diff --git a/docs/reference/gtk/migrating-GtkEntry-icons.sgml b/docs/reference/gtk/migrating-GtkEntry-icons.sgml
index 2687c63a93..b6cbee41c6 100644
--- a/docs/reference/gtk/migrating-GtkEntry-icons.sgml
+++ b/docs/reference/gtk/migrating-GtkEntry-icons.sgml
@@ -25,6 +25,58 @@ gtk_entry_set_icon_from_stock (entry, GTK_ICON_ENTRY_PRIMARY, GTK_STOCK_NEW);
   </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 
diff --git a/docs/reference/gtk/tmpl/gtkentry.sgml b/docs/reference/gtk/tmpl/gtkentry.sgml
index 99f04f94c3..4f38e627bb 100644
--- a/docs/reference/gtk/tmpl/gtkentry.sgml
+++ b/docs/reference/gtk/tmpl/gtkentry.sgml
@@ -34,7 +34,7 @@ icons can be activatable by clicking, can be set up as drag source and
 can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
 one of the various other functions that set an icon from a stock id, an
 icon name or a pixbuf. To trigger an action when the user clicks an icon,
-connect to the #GtkEntry::icon-pressed signal. To allow DND operations
+connect to the #GtkEntry::icon-press signal. To allow DND operations
 from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on 
 an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
 for markup.
@@ -737,11 +737,11 @@ The #GtkEntry-struct struct contains only private data.
 
 <!-- ##### ENUM GtkEntryIconPosition ##### -->
 <para>
-
+Specifies the side of the entry at which an icon is placed.
 </para>
 
-@GTK_ENTRY_ICON_PRIMARY: 
-@GTK_ENTRY_ICON_SECONDARY: 
+@GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
+@GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).
 
 <!-- ##### FUNCTION gtk_entry_set_icon_from_pixbuf ##### -->
 <para>