From 321682871b6547c73d6b8df61643bcc73a0555f7 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 3 Mar 2011 22:40:48 -0500 Subject: [PATCH] Try harder to explain GApplicationCommandline Trying to answer some of the questions in https://bugzilla.gnome.org/show_bug.cgi?id=643468 --- gio/gapplication.c | 9 +++-- gio/gapplicationcommandline.c | 38 +++++++++++++++++- gio/tests/Makefile.am | 4 ++ gio/tests/gapplication-example-cmdline3.c | 65 +++++++++++++++++++++++++++++++ 4 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 gio/tests/gapplication-example-cmdline3.c diff --git a/gio/gapplication.c b/gio/gapplication.c index 44f1cdb..48f8065 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -583,8 +583,11 @@ g_application_class_init (GApplicationClass *class) * passed commandline * * The ::command-line signal is emitted on the primary instance when - * a commandline is not handled locally. See g_application_run() for - * more information. + * a commandline is not handled locally. See g_application_run() and + * the #GApplicationCommandline documentation for more information. + * + * Returns: An integer that is set as the exit status for the calling + * process. See g_application_command_line_set_exit_status(). */ g_application_signals[SIGNAL_COMMAND_LINE] = g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST, @@ -937,7 +940,7 @@ g_application_get_is_remote (GApplication *application) * This is the point at which the application discovers if it is the * primary instance or merely acting as a remote for an already-existing * primary instance. This is implemented by attempting to acquire the - * application identifier as a uniue bus name on the session bus using + * application identifier as a unique bus name on the session bus using * GDBus. * * Due to the internal architecture of GDBus, method calls can be diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index b8d788a..af9e4ce 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -52,7 +52,23 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * of this object (ie: the process exits when the last reference is * dropped). * + * The main use for #GApplicationCommandline (and the + * #GApplication::command-line signal) is 'Emacs server' like use cases: + * You can set the EDITOR environment variable to have + * e.g. git use your favourite editor to edit commit messages, and if you + * already have an instance of the editor running, the editing will happen + * in the running instance, instead of opening a new one. An important + * aspect of this use case is that the process that gets started by git + * does not return until the editing is done. + * * Handling commandline arguments with GApplication + * + * A simple example where the commandline is completely handled + * in the ::command-line handler. The calling process exits once the + * signal handler in the main instance has returned, and the return + * value of the signal handler becomes the exit status of the calling + * process. + * * * * FIXME: MISSING XINCLUDE CONTENT @@ -60,13 +76,33 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * * * - * Complicated commandline handling + * Split commandline handling + * + * An example of split commandline handling. Options that start with + * --local- are handled locally, all other options are + * passed to the ::command-line handler which runs in the main instance. + * * * * FIXME: MISSING XINCLUDE CONTENT * * * + * + * Deferred commandline handling + * + * An example of deferred commandline handling. Here, the commandline is + * not completely handled in the ::command-line handler. Instead, we keep + * a reference to the GApplicationCommandline object and handle it later + * (in this example, in an idle). Note that it is necessary to hold the + * application until you are done with the commandline. + * + * + * + * FIXME: MISSING XINCLUDE CONTENT + * + * + * **/ enum diff --git a/gio/tests/Makefile.am b/gio/tests/Makefile.am index 5f49e6c..46b0efa 100644 --- a/gio/tests/Makefile.am +++ b/gio/tests/Makefile.am @@ -90,6 +90,7 @@ SAMPLE_PROGS = \ gapplication-example-open \ gapplication-example-cmdline \ gapplication-example-cmdline2 \ + gapplication-example-cmdline3 \ gapplication-example-actions \ $(NULL) @@ -328,6 +329,9 @@ gapplication_example_cmdline_LDADD = $(progs_ldadd) gapplication_example_cmdline2_SOURCES = gapplication-example-cmdline2.c gapplication_example_cmdline2_LDADD = $(progs_ldadd) +gapplication_example_cmdline3_SOURCES = gapplication-example-cmdline3.c +gapplication_example_cmdline3_LDADD = $(progs_ldadd) + gapplication_example_actions_SOURCES = gapplication-example-actions.c gapplication_example_actions_LDADD = $(progs_ldadd) diff --git a/gio/tests/gapplication-example-cmdline3.c b/gio/tests/gapplication-example-cmdline3.c new file mode 100644 index 0000000..59704ed --- /dev/null +++ b/gio/tests/gapplication-example-cmdline3.c @@ -0,0 +1,65 @@ +#include +#include +#include + +static gboolean +my_cmdline_handler (gpointer data) +{ + GApplicationCommandLine *cmdline = data; + gchar **argv; + gint argc; + gint i; + + argv = g_application_command_line_get_arguments (cmdline, &argc); + + g_application_command_line_print (cmdline, + "This text is written back\n" + "to stdout of the caller\n"); + + for (i = 0; i < argc; i++) + g_print ("argument %d: %s\n", i, argv[i]); + + g_strfreev (argv); + + g_application_command_line_set_exit_status (cmdline, 1); + + /* we are done handling this commandline */ + g_object_unref (cmdline); + + return FALSE; +} + +static int +command_line (GApplication *application, + GApplicationCommandLine *cmdline) +{ + /* keep the application running until we are done with this commandline */ + g_application_hold (application); + + g_object_set_data_full (G_OBJECT (cmdline), + "application", application, + (GDestroyNotify)g_application_release); + + g_object_ref (cmdline); + g_idle_add (my_cmdline_handler, cmdline); + + return 0; +} + +int +main (int argc, char **argv) +{ + GApplication *app; + int status; + + app = g_application_new ("org.gtk.TestApplication", + G_APPLICATION_HANDLES_COMMAND_LINE); + g_signal_connect (app, "command-line", G_CALLBACK (command_line), NULL); + g_application_set_inactivity_timeout (app, 10000); + + status = g_application_run (app, argc, argv); + + g_object_unref (app); + + return status; +} -- 2.7.4