Add a migration chapter for label links

4 files changed, 38 insertions, 5 deletions

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index d7ffd71bcb..72aed73800 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -129,17 +129,18 @@ content_files =					\
 	drawing-model.xml			\
 	glossary.xml				\
 	migrating-checklist.sgml		\
+	migrating-GtkAboutDialog.sgml		\
 	migrating-GtkAction.sgml		\
+	migrating-GtkAssistant.sgml		\
+	migrating-GtkBuilder.sgml		\
+	migrating-GtkColorButton.sgml		\
 	migrating-GtkComboBox.sgml		\
 	migrating-GtkEntry-icons.sgml		\
 	migrating-GtkFileChooser.sgml		\
 	migrating-GtkIconView.sgml		\
-	migrating-GtkAboutDialog.sgml		\
-	migrating-GtkColorButton.sgml		\
-	migrating-GtkAssistant.sgml		\
-	migrating-GtkRecentChooser.sgml 	\
+	migrating-GtkLabel-links.sgml		\
 	migrating-GtkLinkButton.sgml		\
-	migrating-GtkBuilder.sgml		\
+	migrating-GtkRecentChooser.sgml 	\
         migrating-GtkTooltip.sgml		\
 	objects_grouped.sgml			\
 	osx.sgml				\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 97015103a9..0d27e5ff45 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -432,6 +432,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <xi:include href="xml/migrating-GtkBuilder.sgml" />
     <xi:include href="xml/migrating-GtkTooltip.sgml" />
     <xi:include href="xml/migrating-GtkEntry-icons.sgml" />
+    <xi:include href="xml/migrating-GtkLabel-links.sgml" />
   </part>
 
   <part>
@@ -483,4 +484,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <title>Index of new symbols in 2.16</title>
     <xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include>
   </index>
+  <index id="api-index-2-18" role="2.18">
+    <title>Index of new symbols in 2.18</title>
+    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
+  </index>
 </book>
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 72051c28fc..d300ea6322 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -2274,6 +2274,7 @@ gtk_label_set_use_markup
 gtk_label_set_use_underline
 gtk_label_set_single_line_mode
 gtk_label_set_angle
+gtk_label_get_current_uri
 <SUBSECTION Standard>
 GTK_LABEL
 GTK_IS_LABEL
diff --git a/docs/reference/gtk/migrating-GtkLabel-links.sgml b/docs/reference/gtk/migrating-GtkLabel-links.sgml
new file mode 100644
index 0000000000..3a94694f2b
--- /dev/null
+++ b/docs/reference/gtk/migrating-GtkLabel-links.sgml
@@ -0,0 +1,26 @@
+<?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-label-links">
+
+  <title>Migrating from SexyUrlLabel to GtkLabel</title>
+
+  <para>
+    GTK+ 2.18 supports showing links inside a #GtkLabel, similar to
+    SexyUrlLabel. Porting from SexyUrlLabel to GtkLabel is relatively
+    straightforward. GtkLabel accepts links in the markup using the
+    same HTML <tag>a</tag> notation that SexyUrlLabel uses. In addition
+    to the href attribute, GtkLabel accepts a title attribute that
+    is displayed as a tooltip on the link. Instead of
+    sexy_url_label_set_markup(), just call gtk_label_set_markup().
+  </para>
+  <para>
+    One difference between the two APIs is that the ::url-activated signal
+    from SexyUrlLabel has been replaced by the #GtkLabel::activate-link
+    signal. The activated URI is no longer passed as an argument to the
+    signal handler. Instead, call gtk_label_get_current_uri() to obtain it.
+    However, the need for connecting to this signal is greatly reduced,
+    since GtkLabel has a default handler that calls gtk_show_uri().
+  </para>
+</chapter>