[gtkmm-documentation] Update chapter 9, Container Widgets, for gtkmm-4.0

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 1cd2baa9816ae8b82e1422c1070aec99b0ba9594
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Feb 9 10:55:11 2017 +0100

    Update chapter 9, Container Widgets, for gtkmm-4.0
    
    * docs/tutorial/C/index-in.docbook: Remove info on the removed Alignment and
    Table widgets. In the explanation of box packing options, explain margins
    instead of the removed padding.
    * docs/tutorial/C/figures/alignment.png:
    * examples/book/alignment/examplewindow.[cc|h]:
    * examples/book/alignment/main.cc: Removed files.
    * docs/tutorial/Makefile.am: Remove alignment.png.
    * examples/Makefile.am: Remove book/alignment/*.
    * docs/tutorial/C/figures/box_packing[1|2|3].png: Updated.
    * examples/book/box/examplewindow.cc:
    * examples/book/box/packbox.[cc|h]: Use margins instead of padding.
    * examples/book/box/main.cc: Give argc,argv to Application::run().

 docs/tutorial/C/figures/alignment.png    |  Bin 4813 -> 0 bytes
 docs/tutorial/C/figures/box_packing1.png |  Bin 28153 -> 64686 bytes
 docs/tutorial/C/figures/box_packing2.png |  Bin 24333 -> 55261 bytes
 docs/tutorial/C/figures/box_packing3.png |  Bin 9397 -> 17381 bytes
 docs/tutorial/C/index-in.docbook         |   97 +++++++++++------------------
 docs/tutorial/Makefile.am                |    1 -
 examples/Makefile.am                     |    6 --
 examples/book/alignment/examplewindow.cc |   42 -------------
 examples/book/alignment/examplewindow.h  |   38 ------------
 examples/book/alignment/main.cc          |   30 ---------
 examples/book/box/examplewindow.cc       |   38 +++++++-----
 examples/book/box/main.cc                |   15 ++---
 examples/book/box/packbox.cc             |   26 ++++++---
 examples/book/box/packbox.h              |    4 +-
 14 files changed, 84 insertions(+), 213 deletions(-)
---
diff --git a/docs/tutorial/C/figures/box_packing1.png b/docs/tutorial/C/figures/box_packing1.png
index 1af334b..97dbb3b 100644
Binary files a/docs/tutorial/C/figures/box_packing1.png and b/docs/tutorial/C/figures/box_packing1.png differ
diff --git a/docs/tutorial/C/figures/box_packing2.png b/docs/tutorial/C/figures/box_packing2.png
index 1783b12..00df3fc 100644
Binary files a/docs/tutorial/C/figures/box_packing2.png and b/docs/tutorial/C/figures/box_packing2.png differ
diff --git a/docs/tutorial/C/figures/box_packing3.png b/docs/tutorial/C/figures/box_packing3.png
index b8f655b..956f601 100644
Binary files a/docs/tutorial/C/figures/box_packing3.png and b/docs/tutorial/C/figures/box_packing3.png differ
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 50ab1f7..15f001d 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -1770,50 +1770,25 @@ resizes the top-level window.
 </sect2>
 
 
-<sect2 id="sec-alignment">
-<title>Alignment</title>
+<sect2 id="sec-other-single-item-containers">
+<title>Other Single-item Containers</title>
 
 <para>
-The <classname>Alignment</classname> widget allows you to place a widget at a
-position and size relative to the size of the <classname>Alignment</classname>
-widget itself. For instance, it might be used to center a widget.
+There are other single-item containers. See the reference documentation for a
+complete list. Here are links to some example programs that show containers,
+which are not mentioned elsewhere in this tutorial.
 </para>
 
-<para>
-The <classname>Alignment</classname> widget is deprecated from &gtkmm; version 3.14
-and should not be used in newly-written code. Use <classname>Gtk::Widget</classname>'s
-alignment and margin methods instead.
-</para>
-
-<sect3 id="alignment-example">
-<title>Example</title>
-<para>
-This example right-aligns a button in a window by using
-<methodname>Gtk::Widget::set_halign()</methodname>.
-</para>
-
-<figure id="figure-alignment">
-  <title>Alignment</title>
-  <screenshot>
-    <graphic format="PNG" fileref="&url_figures_base;alignment.png"/>
-  </screenshot>
-</figure>
-
-<para><ulink url="&url_examples_base;alignment">Source Code</ulink></para>
-
-<para>
-See the <link linkend="sec-progressbar">ProgressBar</link> section for another
-example that uses <methodname>set_halign()</methodname>.
-</para>
-
-</sect3>
+<para><ulink url="&url_examples_base;actionbar">Source Code, ActionBar</ulink></para>
+<para><ulink url="&url_examples_base;expander">Source Code, Expander</ulink></para>
+<para><ulink url="&url_examples_base;popover">Source Code, Popover</ulink></para>
 
 </sect2>
 
 </sect1>
 
 <sect1 id="sec-multi-item-containers">
-<title>Multiple-item widgets </title>
+<title>Multiple-item Containers </title>
 
 <para>
 Multiple-item widgets inherit from <classname>Gtk::Container</classname>; just
@@ -1858,7 +1833,7 @@ you can arrange your widgets in rows, columns,
 and/or grids. &gtkmm; can size your window automatically, based on the
 sizes of the widgets it contains. And the sizes of the widgets are, in turn, determined by the amount of 
text they contain, or the minimum and maximum sizes that you specify, and/or how you have requested that the 
available space should be shared between sets of widgets.
 You can perfect your layout by
-specifying padding distance and centering values for each of your widgets. &gtkmm; then uses
+specifying margins and centering values for each of your widgets. &gtkmm; then uses
 all this information to resize and reposition everything sensibly and smoothly when the user manipulates the 
window. </para>
 
 <para>
@@ -1972,7 +1947,7 @@ There are several options governing how  widgets are to be packed, and this can
 be confusing at first. If you have difficulties then it is sometimes a good
 idea to play with the <application>glade</application> GUI designer to see what
 is possible. You might even decide to use the
-<application>Gtk::Builder</application> API to load your GUI at runtime.
+<classname>Gtk::Builder</classname> API to load your GUI at runtime.
 </para>
 
 <para>
@@ -1998,8 +1973,7 @@ several buttons. Each of the buttons on a line is packed into the
 This is the declaration of the <methodname>pack_start()</methodname> method:
 </para>
 <programlisting>void pack_start(Gtk::Widget&amp; child,
-                Gtk::PackOptions options = Gtk::PACK_EXPAND_WIDGET,
-                guint padding = 0);</programlisting>
+                Gtk::PackOptions options = Gtk::PACK_EXPAND_WIDGET);</programlisting>
 
 <para>
 The first argument is the widget you're packing. In our example these are all <classname>Button</classname>s.
@@ -2015,8 +1989,8 @@ The <parameter>options</parameter> argument can take one of these three options:
 </para>
 
 <para>
-The <parameter>padding</parameter> argument specifies the width of an extra
-border area to leave around the packed widget.
+Margins are set with the child widget's <methodname>set_margin()</methodname>,
+<methodname>set_margin_start()</methodname> etc. methods.
 </para>
 
 <para><ulink url="&url_refdocs_base_gtk;Box.html">Reference</ulink></para>
@@ -2038,9 +2012,10 @@ each widget.
 
 <para>
 What's the difference between spacing (set when the box is created)
-and padding (set when elements are packed)? Spacing is added between
-objects, and padding is added on either side of a widget. The following
-figure should make it clearer:
+and margins (set separately for each child widget)? Spacing is added between
+objects, and margins are added on one or more sides of a widget. The following
+figure should make it clearer. The shown margins are the left and right margins
+of each button in the row.
 </para>
 
 <figure id="figure-box-packing2">
@@ -2064,12 +2039,13 @@ with <classname>Gtk::Application</classname>.
 <listitem><para>
 Handle the options in <function>main()</function> and hide them from
 <classname>Gtk::Application</classname> by setting <literal>argc = 1</literal>
-in the call to <methodname>Gtk::Application::create()</methodname>.
+in the call to <methodname>Gtk::Application::run()</methodname>.
 </para></listitem>
 
 <listitem><para>
-Give all command-line options to <methodname>Gtk::Application::create()</methodname>
-and add the flag <literal>Gio::APPLICATION_HANDLES_COMMAND_LINE</literal>.
+Give all command-line options to <methodname>Gtk::Application::run()</methodname>
+and add the flag <literal>Gio::APPLICATION_HANDLES_COMMAND_LINE</literal>
+to <methodname>Gtk::Application::create()</methodname>.
 Connect a signal handler to the <literal>command_line</literal> signal, and
 handle the command-line options in the signal handler.</para>
 
@@ -2178,19 +2154,6 @@ spanning two columns.
 
 </sect2>
 
-<sect2 id="sec-table">
-<title>Table</title>
-
-<para>
-<classname>Gtk::Table</classname> allows us to place widgets in a grid,
-similar to <classname>Gtk::Grid</classname>.
-</para>
-<para>
-<classname>Gtk::Table</classname> is deprecated from &gtkmm; version 3.4 and should
-not be used in newly-written code. Use <classname>Gtk::Grid</classname> instead.
-</para>
-</sect2>
-
 <sect2 id="sec-notebook">
 <title>Notebook</title>
 
@@ -2255,7 +2218,7 @@ To determine the currently-visible page, use the <methodname>get_current_page()<
 </para>
 
 <para>
-To set the title of a page, use the <methodname>set_page_title()</methodname> method. The header and side 
images of a page can be set with the <methodname>set_page_header_image()</methodname> and 
<methodname>set_page_side_image()</methodname> methods.
+To set the title of a page, use the <methodname>set_page_title()</methodname> method.
 </para>
 
 <para>
@@ -2279,6 +2242,20 @@ To add widgets to the action area, use the <methodname>add_action_widget()</meth
 
 </sect2>
 
+<sect2 id="sec-other-multi-item-containers">
+<title>Other Multi-item Containers</title>
+
+<para>
+There are other multi-item containers. See the reference documentation for a
+complete list. Here are links to some example programs that show containers,
+which are not mentioned elsewhere in this tutorial.
+</para>
+
+<para><ulink url="&url_examples_base;flowbox">Source Code, FlowBox</ulink></para>
+<para><ulink url="&url_examples_base;iconview">Source Code, IconView</ulink></para>
+
+</sect2>
+
 </sect1>
 
 </chapter>
diff --git a/docs/tutorial/Makefile.am b/docs/tutorial/Makefile.am
index 36b9135..33b625e 100644
--- a/docs/tutorial/Makefile.am
+++ b/docs/tutorial/Makefile.am
@@ -24,7 +24,6 @@ HELP_FILES = \
        index.docbook
 
 HELP_MEDIA =                                   \
-       figures/alignment.png                   \
        figures/aspectframe.png                 \
        figures/assistant.png                   \
        figures/box_packing1.png                \
diff --git a/examples/Makefile.am b/examples/Makefile.am
index 3043201..e575bc0 100644
--- a/examples/Makefile.am
+++ b/examples/Makefile.am
@@ -10,7 +10,6 @@ LDADD       = $(GTKMM_LIBS)
 
 check_PROGRAMS =                                       \
        book/actionbar/example                          \
-       book/alignment/example                          \
        book/application/simple/example \
        book/application/command_line_handling/example \
        book/application/app_and_win_menus/example \
@@ -171,11 +170,6 @@ book_application_app_and_win_menus_example_SOURCES =               \
        book/application/app_and_win_menus/examplewindow.h      \
        book/application/app_and_win_menus/main.cc
 
-book_alignment_example_SOURCES =               \
-       book/alignment/examplewindow.cc         \
-       book/alignment/examplewindow.h          \
-       book/alignment/main.cc
-
 book_aspectframe_example_SOURCES =             \
        book/aspectframe/examplewindow.cc       \
        book/aspectframe/examplewindow.h        \
diff --git a/examples/book/box/examplewindow.cc b/examples/book/box/examplewindow.cc
index 5b4caa5..46b9c15 100644
--- a/examples/book/box/examplewindow.cc
+++ b/examples/book/box/examplewindow.cc
@@ -24,13 +24,18 @@ ExampleWindow::ExampleWindow(int which)
 {
   set_title("Gtk::Box example");
 
+  m_separator1.set_margin_top(5);
+  m_separator1.set_margin_bottom(5);
+  m_separator2.set_margin_top(5);
+  m_separator2.set_margin_bottom(5);
+
   PackBox *pPackBox1, *pPackBox2, *pPackBox3, *pPackBox4, *pPackBox5;
 
   switch(which)
   {
     case 1:
     {
-      m_Label1.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL); set_homogeneous(false);");
+      m_Label1.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL, 0); set_homogeneous(false);");
 
       // Align the label to the left side.
       m_Label1.set_halign(Gtk::ALIGN_START);
@@ -42,40 +47,40 @@ ExampleWindow::ExampleWindow(int which)
       m_box1.pack_start(m_Label1, Gtk::PACK_SHRINK);
 
       // Create a PackBox - homogeneous = false, spacing = 0,
-      // options = Gtk::PACK_SHRINK, padding = 0
+      // options = Gtk::PACK_SHRINK, margin = 0
       pPackBox1 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_SHRINK));
       m_box1.pack_start(*pPackBox1, Gtk::PACK_SHRINK);
 
       // Create a PackBox - homogeneous = false, spacing = 0,
-      // options = Gtk::PACK_EXPAND_PADDING, padding = 0
+      // options = Gtk::PACK_EXPAND_PADDING, margin = 0
       pPackBox2 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_PADDING));
       m_box1.pack_start(*pPackBox2, Gtk::PACK_SHRINK);
 
       // Create a PackBox - homogeneous = false, spacing = 0,
-      // options = Gtk::PACK_EXPAND_WIDGET, padding = 0
+      // options = Gtk::PACK_EXPAND_WIDGET, margin = 0
       pPackBox3 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_WIDGET));
       m_box1.pack_start(*pPackBox3, Gtk::PACK_SHRINK);
 
       // pack the separator into the vbox.  Remember each of these
       // widgets are being packed into a vbox, so they'll be stacked
       // vertically.
-      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK, 5);
+      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK);
 
       // create another new label, and show it.
-      m_Label2.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL); set_homogeneous(true);");
+      m_Label2.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL, 0); set_homogeneous(true);");
       m_Label2.set_halign(Gtk::ALIGN_START);
       m_Label2.set_valign(Gtk::ALIGN_START);
       m_box1.pack_start(m_Label2, Gtk::PACK_SHRINK);
 
-      // Args are: homogeneous, spacing, options, padding
+      // Args are: homogeneous, spacing, options, margin
       pPackBox4 = Gtk::manage(new PackBox(true, 0, Gtk::PACK_EXPAND_PADDING));
       m_box1.pack_start(*pPackBox4, Gtk::PACK_SHRINK);
 
-      // Args are: homogeneous, spacing, options, padding
+      // Args are: homogeneous, spacing, options, margin
       pPackBox5 = Gtk::manage(new PackBox(true, 0, Gtk::PACK_EXPAND_WIDGET));
       m_box1.pack_start(*pPackBox5, Gtk::PACK_SHRINK);
 
-      m_box1.pack_start(m_separator2, Gtk::PACK_SHRINK, 5);
+      m_box1.pack_start(m_separator2, Gtk::PACK_SHRINK);
 
       break;
     }
@@ -94,9 +99,9 @@ ExampleWindow::ExampleWindow(int which)
       pPackBox2 = Gtk::manage(new PackBox(false, 10, Gtk::PACK_EXPAND_WIDGET));
       m_box1.pack_start(*pPackBox2, Gtk::PACK_SHRINK);
 
-      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK, 5);
+      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK);
 
-      m_Label2.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL); set_homogeneous(false);");
+      m_Label2.set_text("Gtk::Box(Gtk::ORIENTATION_HORIZONTAL, 0); set_homogeneous(false);");
       m_Label2.set_halign(Gtk::ALIGN_START);
       m_Label2.set_valign(Gtk::ALIGN_START);
       m_box1.pack_start(m_Label2, Gtk::PACK_SHRINK);
@@ -107,7 +112,7 @@ ExampleWindow::ExampleWindow(int which)
       pPackBox4 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_WIDGET, 10));
       m_box1.pack_start(*pPackBox4, Gtk::PACK_SHRINK);
 
-      m_box1.pack_start(m_separator2, Gtk::PACK_SHRINK, 5);
+      m_box1.pack_start(m_separator2, Gtk::PACK_SHRINK);
 
       break;
     }
@@ -127,15 +132,15 @@ ExampleWindow::ExampleWindow(int which)
 
       m_box1.pack_start(*pPackBox1, Gtk::PACK_SHRINK);
 
-      // this explicitly sets the separator to 500 pixels wide by 5 pixels
-      // high.  This is so the hbox we created will also be 500 pixels wide,
+      // This explicitly sets the separator to 700 pixels wide by 5 pixels
+      // high.  This is so the hbox we created will also be 700 pixels wide,
       // and the "end" label will be separated from the other labels in the
       // hbox.  Otherwise, all the widgets in the hbox would be packed as
       // close together as possible.
-      m_separator1.set_size_request(500, 5);
+      m_separator1.set_size_request(700, 5);
 
       // pack the separator into the vbox.
-      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK, 5);
+      m_box1.pack_start(m_separator1, Gtk::PACK_SHRINK);
 
       break;
     }
@@ -152,7 +157,6 @@ ExampleWindow::ExampleWindow(int which)
               &ExampleWindow::on_button_quit_clicked) );
 
   // pack the button into the quitbox.
-  // The last 2 arguments to Box::pack_start are: options, padding.
   m_boxQuit.pack_start(m_buttonQuit, Gtk::PACK_EXPAND_PADDING);
   m_box1.pack_start(m_boxQuit, Gtk::PACK_SHRINK);
 
diff --git a/examples/book/box/main.cc b/examples/book/box/main.cc
index b6bf4b2..9c8f872 100644
--- a/examples/book/box/main.cc
+++ b/examples/book/box/main.cc
@@ -1,5 +1,3 @@
-//$Id: main.cc 2 2003-01-21 13:41:59Z murrayc $ -*- c++ -*-
-
 /* gtkmm example Copyright (C) 2002 gtkmm development team
  *
  * This program is free software; you can redistribute it and/or modify
@@ -50,15 +48,16 @@ int main(int argc, char *argv[])
     return EXIT_FAILURE;
   }
 
+  int argc1 = argc;
+
 #if GTK_APPLICATION_RECEIVES_COMMAND_LINE_ARGUMENTS
-  // The command line arguments must be checked before Gtk::Application::run()
-  // is called. The Gio::APPLICATION_HANDLES_COMMAND_LINE flag and the
+  // The Gio::APPLICATION_HANDLES_COMMAND_LINE flag and the
   // on_command_line() signal handler are not necessary. This program is simpler
-  // without them, and with argc = 1 in the call to Gtk::Application::create().
+  // without them, and with argc = 1 in the call to Gtk::Application::run().
   // They are included to show a program with Gio::APPLICATION_HANDLES_COMMAND_LINE.
   // Gio::APPLICATION_NON_UNIQUE makes it possible to run several instances of
   // this application simultaneously.
-  auto app = Gtk::Application::create(argc, argv,
+  auto app = Gtk::Application::create(
     "org.gtkmm.example", Gio::APPLICATION_HANDLES_COMMAND_LINE | Gio::APPLICATION_NON_UNIQUE);
 
   // Note after = false.
@@ -68,11 +67,11 @@ int main(int argc, char *argv[])
 #else
   // Gio::APPLICATION_NON_UNIQUE makes it possible to run several instances of
   // this application simultaneously.
-  int argc1 = 1; // Don't give the command line arguments to Gtk::Application.
+  argc1 = 1; // Don't give the command line arguments to Gtk::Application.
   auto app = Gtk::Application::create(argc1, argv,
     "org.gtkmm.example", Gio::APPLICATION_NON_UNIQUE);
 #endif
 
   ExampleWindow window(std::atoi(argv[1]));
-  return app->run(window); //Shows the window and returns when it is closed.
+  return app->run(window, argc1, argv); // Shows the window and returns when it is closed.
 }
diff --git a/examples/book/box/packbox.cc b/examples/book/box/packbox.cc
index 9fde9d2..de1b672 100644
--- a/examples/book/box/packbox.cc
+++ b/examples/book/box/packbox.cc
@@ -19,22 +19,32 @@
 #include "packbox.h"
 
 PackBox::PackBox(bool homogeneous, int spacing, Gtk::PackOptions options,
-        int padding)
+        int margin)
 : Gtk::Box(Gtk::ORIENTATION_HORIZONTAL, spacing),
   m_button1("box.pack_start("),
   m_button2("button,"),
-  m_button3((options == Gtk::PACK_SHRINK) ? "Gtk::PACK_SHRINK" :
+  m_button3((options == Gtk::PACK_SHRINK) ? "Gtk::PACK_SHRINK);" :
             ((options == Gtk::PACK_EXPAND_PADDING) ?
-             "Gtk::PACK_EXPAND_PADDING" : "Gtk::PACK_EXPAND_WIDGET"))
+             "Gtk::PACK_EXPAND_PADDING);" : "Gtk::PACK_EXPAND_WIDGET);"))
 {
   set_homogeneous(homogeneous);
 
-  pack_start(m_button1, options, padding);
-  pack_start(m_button2, options, padding);
-  pack_start(m_button3, options, padding);
+  m_button1.set_margin_start(margin);
+  m_button1.set_margin_end(margin);
+  pack_start(m_button1, options);
 
-  m_pbutton4 = new Gtk::Button(Glib::ustring::format(padding) + ");");
-  pack_start(*m_pbutton4, options, padding);
+  m_button2.set_margin_start(margin);
+  m_button2.set_margin_end(margin);
+  pack_start(m_button2, options);
+
+  m_button3.set_margin_start(margin);
+  m_button3.set_margin_end(margin);
+  pack_start(m_button3, options);
+
+  m_pbutton4 = new Gtk::Button("margin=" + Glib::ustring::format(margin));
+  m_pbutton4->set_margin_start(margin);
+  m_pbutton4->set_margin_end(margin);
+  pack_start(*m_pbutton4, options);
 }
 
 PackBox::~PackBox()
diff --git a/examples/book/box/packbox.h b/examples/book/box/packbox.h
index 59f4ac3..0383de3 100644
--- a/examples/book/box/packbox.h
+++ b/examples/book/box/packbox.h
@@ -1,5 +1,3 @@
-//$Id: packbox.h 705 2006-07-19 02:55:32Z jjongsma $ -*- c++ -*-
-
 /* gtkmm example Copyright (C) 2002 gtkmm development team
  *
  * This program is free software; you can redistribute it and/or modify
@@ -24,7 +22,7 @@
 class PackBox : public Gtk::Box
 {
 public:
-  PackBox(bool homogeneous, int spacing, Gtk::PackOptions options, int padding = 0);
+  PackBox(bool homogeneous, int spacing, Gtk::PackOptions options, int margin = 0);
   virtual ~PackBox();
 
 protected: