luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-09 19:06:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Bug-790839 GApplication command line --help enhancements

Browse Source 
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
This commit is contained in:
howetuft 2017-12-28 08:39:21 +01:00 committed by Philip Withnall
parent b441c21a09
commit 0e22d19a11
6 changed files with 180 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/gio/gio-sections.txt
View File

@ -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

82
gio/gapplication.c
View File

@ -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)

10
gio/gapplication.h
View File

@ -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

1
gio/tests/Makefile.am
View File

@ -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 \

85
gio/tests/gapplication-example-cmdline4.c Normal file
View File

@ -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;
}

1
gio/tests/meson.build
View File

@ -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],