[glib] Bug-790839 GApplication command line --help enhancements
- From: Philip Withnall <pwithnall src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Bug-790839 GApplication command line --help enhancements
- Date: Wed, 3 Jan 2018 11:08:57 +0000 (UTC)
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]