[glib] Bug-790839 GApplication command line --help enhancements



commit 0e22d19a11529d02c154d6ea538b35b8b4252422
Author: howetuft <howetuft gmail com>
Date:   Thu Dec 28 08:39:21 2017 +0100

    Bug-790839 GApplication command line --help enhancements
    
    In order to enrich information displayed by GApplication command line
    handling when --help is invoked, 3 new methods are proposed:
    . g_application_set_option_context_parameter_string
    . g_application_set_option_context_summary
    . g_application_set_option_context_description
    Those methods interact with the GApplication's internal GOptionContext
    which is created for command line parsing in g_application_parse_command_line.
    (please refer to the GOptionContext class for more information about option
    context, parameter string, summary and description.)
    
    To illustrate the 3 methods, an example is provided:
    . gapplication-example-cmdline4.c

 docs/reference/gio/gio-sections.txt       |    3 +
 gio/gapplication.c                        |   82 +++++++++++++++++++++++++++-
 gio/gapplication.h                        |   10 +++-
 gio/tests/Makefile.am                     |    1 +
 gio/tests/gapplication-example-cmdline4.c |   85 +++++++++++++++++++++++++++++
 gio/tests/meson.build                     |    1 +
 6 files changed, 180 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index b055bbf..c72f0ee 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3232,6 +3232,9 @@ g_application_run
 g_application_add_main_option_entries
 g_application_add_main_option
 g_application_add_option_group
+g_application_set_option_context_parameter_string
+g_application_set_option_context_summary
+g_application_set_option_context_description
 <SUBSECTION>
 g_application_set_default
 g_application_get_default
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 9d880fc..67e6c16 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -246,6 +246,9 @@ struct _GApplicationPrivate
   GSList             *option_groups;
   GHashTable         *packed_options;
   gboolean            options_parsed;
+  gchar              *parameter_string;
+  gchar              *summary;
+  gchar              *description;
 
   /* Allocated option strings, from g_application_add_main_option() */
   GSList             *option_strings;
@@ -484,7 +487,9 @@ g_application_parse_command_line (GApplication   *application,
    */
   g_return_val_if_fail (!application->priv->options_parsed, NULL);
 
-  context = g_option_context_new (NULL);
+  context = g_option_context_new (application->priv->parameter_string);
+  g_option_context_set_summary (context, application->priv->summary);
+  g_option_context_set_description (context, application->priv->description);
 
   gapplication_group = g_option_group_new ("gapplication",
                                            _("GApplication options"), _("Show GApplication options"),
@@ -814,6 +819,77 @@ g_application_add_option_group (GApplication *application,
   application->priv->option_groups = g_slist_prepend (application->priv->option_groups, group);
 }
 
+/**
+ * g_application_set_option_context_parameter_string:
+ * @application: the #GApplication
+ * @parameter_string: (nullable): a string which is displayed
+ *   in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
+ *
+ * Sets the parameter string to be used by the commandline handling of @application.
+ *
+ * This function registers the argument to be passed to g_option_context_new()
+ * when the internal #GOptionContext of @application is created.
+ *
+ * See g_option_context_new() for more information about @parameter_string.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_parameter_string (GApplication *application,
+                                                   const gchar  *parameter_string)
+{
+  g_return_if_fail (G_IS_APPLICATION (application));
+
+  g_free (application->priv->parameter_string);
+  application->priv->parameter_string = g_strdup (parameter_string);
+}
+
+/**
+ * g_application_set_option_context_summary:
+ * @application: the #GApplication
+ * @summary: (nullable): a string to be shown in `--help` output
+ *  before the list of options, or %NULL
+ *
+ * Adds a summary to the @application option context.
+ *
+ * See g_option_context_set_summary() for more information.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_summary (GApplication *application,
+                                          const gchar  *summary)
+{
+  g_return_if_fail (G_IS_APPLICATION (application));
+
+  g_free (application->priv->summary);
+  application->priv->summary = g_strdup (summary);
+}
+
+/**
+ * g_application_set_option_context_description:
+ * @application: the #GApplication
+ * @description: (nullable): a string to be shown in `--help` output
+ *  after the list of options, or %NULL
+ *
+ * Adds a description to the @application option context.
+ *
+ * See g_option_context_set_description() for more information.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_description (GApplication *application,
+                                              const gchar  *description)
+{
+  g_return_if_fail (G_IS_APPLICATION (application));
+
+  g_free (application->priv->description);
+  application->priv->description = g_strdup (description);
+
+}
+
+
 /* vfunc defaults {{{1 */
 static void
 g_application_real_before_emit (GApplication *application,
@@ -1275,6 +1351,10 @@ g_application_finalize (GObject *object)
   if (application->priv->packed_options)
     g_hash_table_unref (application->priv->packed_options);
 
+  g_free (application->priv->parameter_string);
+  g_free (application->priv->summary);
+  g_free (application->priv->description);
+
   g_slist_free_full (application->priv->option_strings, g_free);
 
   if (application->priv->impl)
diff --git a/gio/gapplication.h b/gio/gapplication.h
index a9d2d28..cdb9365 100644
--- a/gio/gapplication.h
+++ b/gio/gapplication.h
@@ -175,7 +175,15 @@ void                    g_application_add_main_option                   (GApplic
 GLIB_AVAILABLE_IN_2_40
 void                    g_application_add_option_group                  (GApplication             
*application,
                                                                          GOptionGroup             *group);
-
+GLIB_AVAILABLE_IN_2_56
+void                    g_application_set_option_context_parameter_string (GApplication             
*application,
+                                                                           const gchar              
*parameter_string);
+GLIB_AVAILABLE_IN_2_56
+void                    g_application_set_option_context_summary        (GApplication             
*application,
+                                                                         const gchar              *summary);
+GLIB_AVAILABLE_IN_2_56
+void                    g_application_set_option_context_description    (GApplication             
*application,
+                                                                         const gchar              
*description);
 GLIB_AVAILABLE_IN_ALL
 gboolean                g_application_get_is_registered                 (GApplication             
*application);
 GLIB_AVAILABLE_IN_ALL
diff --git a/gio/tests/Makefile.am b/gio/tests/Makefile.am
index 71721e5..d7e6554 100644
--- a/gio/tests/Makefile.am
+++ b/gio/tests/Makefile.am
@@ -87,6 +87,7 @@ uninstalled_test_extra_programs = \
        gapplication-example-cmdline            \
        gapplication-example-cmdline2           \
        gapplication-example-cmdline3           \
+       gapplication-example-cmdline4           \
        gapplication-example-dbushooks          \
        gapplication-example-open               \
        gdbus-example-export                    \
diff --git a/gio/tests/gapplication-example-cmdline4.c b/gio/tests/gapplication-example-cmdline4.c
new file mode 100644
index 0000000..1120062
--- /dev/null
+++ b/gio/tests/gapplication-example-cmdline4.c
@@ -0,0 +1,85 @@
+#include <gio/gio.h>
+#include <stdlib.h>
+#include <string.h>
+
+
+static gint
+handle_local_options (GApplication      *application,
+                      GVariantDict      *options,
+                      gpointer           user_data)
+{
+  guint32 count;
+
+  /* Deal (locally) with version option */
+  if (g_variant_dict_lookup (options, "version", "b", &count))
+    {
+      g_print ("This is example-cmdline4, version 1.2.3\n");
+      return EXIT_SUCCESS;
+    }
+
+  return -1;
+
+}
+
+static gint
+command_line (GApplication                *application,
+              GApplicationCommandLine     *cmdline,
+              gpointer                     user_data)
+{
+  guint32 count;
+
+  GVariantDict *options = g_application_command_line_get_options_dict (cmdline);
+
+  /* Deal with arg option */
+  if (g_variant_dict_lookup (options, "flag", "b", &count))
+    {
+      g_application_command_line_print (cmdline, "flag is set\n");
+    }
+
+  return EXIT_SUCCESS;
+}
+
+
+int
+main (int argc, char **argv)
+{
+  GApplication *app;
+  int status;
+
+  GOptionEntry entries[] = {
+    /* A version flag option, to be handled locally */
+    { "version", 'v', G_OPTION_FLAG_NONE, G_OPTION_ARG_NONE, NULL, "Show the application version", NULL },
+
+    /* A dummy flag option, to be handled in primary */
+    { "flag", 'f', G_OPTION_FLAG_NONE, G_OPTION_ARG_NONE, NULL, "A flag argument", NULL },
+
+    { NULL }
+  };
+
+  app = g_application_new ("org.gtk.TestApplication",
+                           G_APPLICATION_HANDLES_COMMAND_LINE);
+
+  g_application_add_main_option_entries (app, entries);
+
+  g_application_set_option_context_parameter_string (app, "- a simple command line example");
+  g_application_set_option_context_summary (app,
+                                            "Summary:\n"
+                                            "This is a simple command line --help example.");
+  g_application_set_option_context_description (app,
+                                                "Description:\n"
+                                                "This example illustrates the use of "
+                                                "g_application command line --help functionalities "
+                                                "(parameter string, summary, description). "
+                                                "It does nothing at all except displaying information "
+                                                "when invoked with --help argument...\n");
+
+  g_signal_connect (app, "handle-local-options", G_CALLBACK (handle_local_options), NULL);
+  g_signal_connect (app, "command-line", G_CALLBACK (command_line), NULL);
+
+  /* This application does absolutely nothing, except if a command line is given */
+  status = g_application_run (app, argc, argv);
+
+  g_object_unref (app);
+
+  return status;
+}
diff --git a/gio/tests/meson.build b/gio/tests/meson.build
index b5399f0..70df559 100644
--- a/gio/tests/meson.build
+++ b/gio/tests/meson.build
@@ -309,6 +309,7 @@ uninstalled_test_extra_programs = [
   ['gapplication-example-cmdline'],
   ['gapplication-example-cmdline2'],
   ['gapplication-example-cmdline3'],
+  ['gapplication-example-cmdline4'],
   ['gapplication-example-dbushooks'],
   ['gapplication-example-open'],
   ['gdbus-daemon', gdbus_daemon_sources],


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]