[gtkmm-documentation] Add "Changes in gtkmm 4" chapter

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 71ac4847a94edaa26004ad0f09c83f5ed4187238
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Dec 15 16:40:21 2016 +0100

    Add "Changes in gtkmm 4" chapter
    
    Describe the changes in locale handling and a few other changes.
    This chapter is not complete. Bug 661588

 docs/tutorial/C/index-in.docbook |   65 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 65 insertions(+), 0 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 27619e4..d4d955a 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -666,6 +666,71 @@ orientation (vertical or horizontal) to be specified without requiring the use o
 
 </chapter>
 
+<chapter id="changes-gtkmm4">
+<title>Changes in &gtkmm; 4</title>
+
+<para>&gtkmm;-4.0 is a new version of the &gtkmm; API that installs in parallel with the
+older &gtkmm;-2.4 and &gtkmm;-3.0 APIs. The last version of the &gtkmm;-3.0 API
+is &gtkmm; 3.22. &gtkmm; 4 has no major fundamental differences to &gtkmm; 3 but
+does make several small changes that were not possible while maintaining binary
+compatibility. If you never used the &gtkmm;-3.0 API then you can safely ignore this chapter.
+</para>
+
+<para>&gtkmm; 4's library is called <literal>libgtkmm-4.0</literal> rather than
+<literal>libgtkmm-3.0</literal> and installs its headers in a similarly-versioned
+directory, so your pkg-config check should ask for <literal>gtkmm-4.0</literal>
+rather than <literal>gtkmm-3.0</literal>.
+</para>
+
+<para>&gtkmm;-4.0 is used in combination with <application>glibmm-2.52</application>,
+which sets the global locale for your program. The older <application>glibmm-2.4</application>
+does not do that, and &gtkmm;-3.0 does it only to some extent. What this means is
+briefly that if your &gtkmm;-3.0 program contains a call to
+<function>std::locale::global(std::locale(""))</function>, you can probably remove it.
+If you don't want <application>glibmm</application> or &gtkmm;
+to set the global locale for you, you should add a call to
+<function>Glib::set_init_to_users_preferred_locale(false)</function> before any call to
+<function>Glib::init()</function> or <methodname>Gtk::Application::create()</methodname>.
+</para>
+<para><ulink url="&url_refdocs_base_glib;set_init_to_users_preferred_locale.html">Reference</ulink></para>
+
+<para>&gtkmm; 4 added some new classes:</para>
+
+<orderedlist>
+<listitem><simpara><classname>Gtk::???</classname>, <classname>Gtk::???</classname> To be 
added.</simpara></listitem>
+</orderedlist>
+
+<para>&gtkmm; 4 also made several small changes to the API, which you will probably encounter
+when porting code that used &gtkmm;-3.0. Here is a short list:</para>
+
+<para>
+<orderedlist>
+<listitem><simpara><classname>Gtk::Button</classname>, <classname>Gtk::ToolButton</classname>,
+  <classname>Gtk::MenuItem</classname> and <classname>Gtk::Switch</classname>
+  implement the <classname>Gtk::Actionable</classname> interface instead of the removed
+  <classname>Gtk::Activatable</classname> interface.</simpara></listitem>
+<listitem><simpara><classname>Gtk::FontButton</classname> implements the 
<classname>Gtk::FontChooser</classname> interface.</simpara></listitem>
+<listitem><simpara><classname>Gtk::Widget</classname>: The <methodname>get_preferred_*_vfunc()</methodname>s
+  have been replaced by <methodname>measure_vfunc()</methodname>. This change only affects
+  custom widgets.</simpara></listitem>
+<listitem><simpara><classname>sigc::slot</classname>s use the 
<classname>sigc::slot&lt;R(Args...)&gt;</classname> syntax.
+  Example: <classname>sigc::slot&lt;void(int, int)&gt;</classname> instead of <classname>sigc::slot&lt;void, 
int, int&gt;</classname>.</simpara></listitem>
+<listitem><simpara><classname>Gtk::DrawingArea</classname> uses a draw function instead of the draw 
signal.</simpara></listitem>
+</orderedlist>
+</para>
+
+<para>All deprecated API was removed in &gtkmm; 4.0, though there will be new deprecations in future 
versions.</para>
+
+<para>As a first step to porting your source code to &gtkmm;-4.0 you should probably ensure
+that your application builds with the deprecated &gtkmm;-3.0 and <application>glibmm-2.4</application>
+API disabled, by defining the macros GTKMM_DISABLE_DEPRECATED, GDKMM_DISABLE_DEPRECATED,
+GLIBMM_DISABLE_DEPRECATED and GIOMM_DISABLE_DEPRECATED. There are some autotools macros
+that can help with this by defining them optionally at build time. See the
+<ulink url="https://wiki.gnome.org/Projects/gtkmm/PortingToGtkmm4";>gtkmm 4 porting wiki page</ulink>
+for more details.</para>
+
+</chapter>
+
 <chapter id="chapter-button-widget">
 <title>Buttons</title>