[gtkmm-documentation] Application example: Use Gio::Application::add_option_group()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 0e7ca8c18c20cef121badc564eb4a5a70d4181f7
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Sun Jun 23 12:55:50 2019 +0200

    Application example: Use Gio::Application::add_option_group()
    
    * examples/book/application/command_line_handling/exampleapplication.[cc|h]:
    Add some options that demonstrate the use of
    Gio::Application::add_option_group().
    
    See issue glibmm#46

 .../command_line_handling/exampleapplication.cc    | 48 +++++++++++++++++++---
 .../command_line_handling/exampleapplication.h     |  7 ++++
 2 files changed, 50 insertions(+), 5 deletions(-)
---
diff --git a/examples/book/application/command_line_handling/exampleapplication.cc 
b/examples/book/application/command_line_handling/exampleapplication.cc
index d9fe8af..9ae8782 100644
--- a/examples/book/application/command_line_handling/exampleapplication.cc
+++ b/examples/book/application/command_line_handling/exampleapplication.cc
@@ -20,7 +20,8 @@
 
 ExampleApplication::ExampleApplication()
 : Gtk::Application("org.gtkmm.examples.application",
-    Gio::Application::Flags(Gio::Application::Flags::HANDLES_OPEN | 
Gio::Application::Flags::HANDLES_COMMAND_LINE))
+    Gio::Application::Flags::HANDLES_OPEN | Gio::Application::Flags::HANDLES_COMMAND_LINE),
+  m_option_group("extra-options", "Extra options", "Show extra options")
 {
   Glib::set_application_name("Gtk::Application Example");
 
@@ -41,7 +42,6 @@ ExampleApplication::ExampleApplication()
   //A bool.
   add_main_option_entry(Gio::Application::OptionType::BOOL, "version", 'v', "Show the application version.");
 
-
   //A std::vector<std::string>.
   add_main_option_entry(Gio::Application::OptionType::FILENAME_VECTOR, G_OPTION_REMAINING);
 
@@ -50,6 +50,28 @@ ExampleApplication::ExampleApplication()
     "string", 's', "The string to use", "string", Glib::OptionEntry::Flags::OPTIONAL_ARG);
   add_main_option_entry_filename(sigc::mem_fun(*this, &ExampleApplication::on_option_arg_filename),
     "name", 'n', "The filename to use", "file");
+
+  // Command-line arguments in a separate OptionGroup.
+  Glib::OptionEntry entry;
+  entry.set_long_name("xint");
+  entry.set_short_name('i');
+  entry.set_description("Extra integer");
+  entry.set_arg_description("number");
+  m_option_group.add_entry(entry, m_arg_int);
+
+  entry.set_long_name("xustring");
+  entry.set_short_name('u');
+  entry.set_description("Extra UTF8 string");
+  entry.set_arg_description("string");
+  m_option_group.add_entry(entry, m_arg_ustring);
+
+  entry.set_long_name("xbool");
+  entry.set_short_name('l');
+  entry.set_description("Extra boolean");
+  entry.set_arg_description("");
+  m_option_group.add_entry(entry, m_arg_boolean);
+
+  add_option_group(m_option_group);
 }
 
 Glib::RefPtr<ExampleApplication> ExampleApplication::create()
@@ -169,6 +191,14 @@ int ExampleApplication::on_command_line(const Glib::RefPtr<Gio::ApplicationComma
   std::vector<std::string> vec_remaining;
   get_arg_value(options, G_OPTION_REMAINING, vec_remaining);
 
+  // The options in m_option_group are not stored in the options VariantDict.
+  // They are available in the data members used in m_option_group.add_entry().
+  // Their values show the options given when the primary instance was started.
+  // To see the difference between the values in on_command_line(), executed in
+  // the primary instance, and the values in on_handle_local_options(), executed
+  // in the local instance, first start one instance of the application.
+  // While that instance is running, start a second instance with other options.
+
   //Note that "foo" and "goo" will not be false/empty here because we
   //handled them in on_handle_local_options() and therefore removed them from
   //the options VariantDict.
@@ -178,12 +208,14 @@ int ExampleApplication::on_command_line(const Glib::RefPtr<Gio::ApplicationComma
     "  hoo = " << hoo_value << std::endl <<
     "  bar = " << bar_value << std::endl <<
     "  version = " << (version_value ? "true" : "false") << std::endl <<
+    "  xint = " << m_arg_int << std::endl <<
+    "  xustring = " << m_arg_ustring << std::endl <<
+    "  xbool = " << (m_arg_boolean ? "true" : "false") << std::endl <<
     "  remaining =";
   for (std::size_t i = 0; i < vec_remaining.size(); ++i)
     std::cout << ' ' << vec_remaining[i];
   std::cout << std::endl;
 
-
   if(vec_remaining.empty())
   {
     //Open a new "document" instead:
@@ -216,12 +248,18 @@ int ExampleApplication::on_handle_local_options(const Glib::RefPtr<Glib::Variant
   bool version_value = false;
   get_arg_value(options, "version", version_value);
 
+  // The options in m_option_group are not stored in the options VariantDict.
+  // They are available in the data members used in m_option_group.add_entry().
+
   std::cout << "on_handle_local_options(), parsed values: " << std::endl <<
     "  foo = " << (foo_value ? "true" : "false") << std::endl <<
     "  goo = " << goo_value << std::endl <<
     "  hoo = " << hoo_value << std::endl <<
     "  bar = " << bar_value << std::endl <<
-    "  version = " << (version_value ? "true" : "false") << std::endl;
+    "  version = " << (version_value ? "true" : "false") << std::endl <<
+    "  xint = " << m_arg_int << std::endl <<
+    "  xustring = " << m_arg_ustring << std::endl <<
+    "  xbool = " << (m_arg_boolean ? "true" : "false") << std::endl;
 
   //Remove some options to show that we have handled them in the local instance,
   //so they won't be passed to the primary (remote) instance:
@@ -240,7 +278,7 @@ int ExampleApplication::on_handle_local_options(const Glib::RefPtr<Glib::Variant
   }
 
   //If the command line parameters were invalid,
-  //complain and exist with a failure code:
+  //complain and exit with a failure code:
   if(goo_value == "ungoo")
   {
      std::cerr << "goo cannot be ungoo." << std::endl;
diff --git a/examples/book/application/command_line_handling/exampleapplication.h 
b/examples/book/application/command_line_handling/exampleapplication.h
index 42df37c..21f4edb 100644
--- a/examples/book/application/command_line_handling/exampleapplication.h
+++ b/examples/book/application/command_line_handling/exampleapplication.h
@@ -41,6 +41,13 @@ protected:
   bool on_option_arg_filename(const Glib::ustring& option_name,
     const std::string& value, bool has_value);
 
+  // These members should live as long as the OptionGroup to which they are added,
+  // and as long as the Application to which that OptionGroup is added.
+  int m_arg_int = 0;
+  Glib::ustring m_arg_ustring;
+  bool m_arg_boolean = false;
+  Glib::OptionGroup m_option_group;
+
 private:
   void create_window(const Glib::RefPtr<Gio::File>& file = Glib::RefPtr<Gio::File>());