[gtkmm-documentation] Fix the book/box example.

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 76b00176b5770018fdf8c28b1b8f554eac146c04
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Tue Nov 20 15:32:01 2012 +0100

    Fix the book/box example.
    
    * docs/tutorial/C/gtkmm-tutorial-in.xml: Describe how to handle command-line
    options with Gtk::Application.
    * examples/book/box/main.cc: Handle the command-line option in a way that
    Gtk::Application accepts.

 ChangeLog                             |    9 +++++
 docs/tutorial/C/gtkmm-tutorial-in.xml |   31 +++++++++++++++++++
 examples/book/box/main.cc             |   54 ++++++++++++++++++++++++++++----
 3 files changed, 87 insertions(+), 7 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index db1192a..38bce30 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2012-11-20  Kjell Ahlstedt <kjell ahlstedt bredband net>
+
+	Fix the book/box example.
+
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Describe how to handle command-line
+	options with Gtk::Application.
+	* examples/book/box/main.cc: Handle the command-line option in a way that
+	Gtk::Application accepts.
+
 2012-11-19  Josà Alburquerque  <jaalburquerque gmail com>
 
 	gmmproc: _WRAP_METHOD: Include docs on wrapping methods with slots.
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index 1964e54..f62526e 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -2099,6 +2099,37 @@ figure should make it clearer:
 </sect4>
 </sect3>
 
+<sect3 id="boxes-command-line-options">
+<title>Gtk::Application and command-line options</title>
+<para>The following example program requires a command-line option.
+The source code shows two ways of handling command-line options in combination
+with <classname>Gtk::Application</classname>.
+</para>
+
+<itemizedlist>
+<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>.
+</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>.
+Connect a signal handler to the <literal>command_line</literal> signal, and
+handle the command-line options in the signal handler.</para>
+
+<para>You must set the optional parameter <literal>after = false</literal> in
+the call to <literal>signal_command_line().connect()</literal>, because your signal
+handler must be called before the default signal handler. You must also call
+<methodname>Gio::Application::activate()</methodname> in the signal handler,
+unless you want your application to exit without showing its main window.
+(<classname>Gio::Application</classname> is a base class of
+<classname>Gtk::Application</classname>.)
+</para></listitem>
+</itemizedlist>
+</sect3>
+
 <sect3 id="box-packing-example">
 <title>Example</title>
 <para>
diff --git a/examples/book/box/main.cc b/examples/book/box/main.cc
index 3df5894..5eb9729 100644
--- a/examples/book/box/main.cc
+++ b/examples/book/box/main.cc
@@ -21,18 +21,58 @@
 #include <iostream>
 #include <cstdlib>
 
-using std::atoi;
+#define GTK_APPLICATION_RECEIVES_COMMAND_LINE_ARGUMENTS 0
 
-int main(int argc, char *argv[])
+#if GTK_APPLICATION_RECEIVES_COMMAND_LINE_ARGUMENTS
+namespace
+{
+int on_command_line(const Glib::RefPtr<Gio::ApplicationCommandLine>& command_line,
+                    Glib::RefPtr<Gtk::Application>& app)
 {
-  Glib::RefPtr<Gtk::Application> app = Gtk::Application::create(argc, argv, "org.gtkmm.example");
+  int argc = 0;
+  char** argv = command_line->get_arguments(argc);
+
+  for (int i = 0; i < argc; ++i)
+    std::cout << "argv[" << i << "] = " << argv[i] << std::endl;
+
+  app->activate(); // Without activate() the window won't be shown.
+  return EXIT_SUCCESS;
+}
+} // anonymous namespace
+#endif
 
-  if(argc != 2)
+
+int main(int argc, char *argv[])
+{
+  if (argc != 2)
   {
-    std::cerr << "usage: packbox num, where num is 1, 2, or 3." << std::endl;
-    return 1;
+    std::cerr << "Usage: example <num>, where <num> is 1, 2, or 3." << std::endl;
+    return EXIT_FAILURE;
   }
 
-  ExampleWindow window( atoi(argv[1]) );
+#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
+  // 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().
+  // 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.
+  Glib::RefPtr<Gtk::Application> app = Gtk::Application::create(argc, argv,
+    "org.gtkmm.example", Gio::APPLICATION_HANDLES_COMMAND_LINE | Gio::APPLICATION_NON_UNIQUE);
+
+  // Note after = false.
+  // Only one signal handler is invoked. This signal handler must run before
+  // the default signal handler, or else it won't run at all.
+  app->signal_command_line().connect(sigc::bind(sigc::ptr_fun(&on_command_line), app), false);
+#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.
+  Glib::RefPtr<Gtk::Application> 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.
 }