Try harder to explain GApplicationCommandline

Trying to answer some of the questions in
https://bugzilla.gnome.org/show_bug.cgi?id=643468
This commit is contained in:
Matthias Clasen 2011-03-03 22:40:48 -05:00
parent 72016418d3
commit 321682871b
4 changed files with 112 additions and 4 deletions

View File

@ -583,8 +583,11 @@ g_application_class_init (GApplicationClass *class)
* passed commandline * passed commandline
* *
* The ::command-line signal is emitted on the primary instance when * The ::command-line signal is emitted on the primary instance when
* a commandline is not handled locally. See g_application_run() for * a commandline is not handled locally. See g_application_run() and
* more information. * 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_application_signals[SIGNAL_COMMAND_LINE] =
g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST, 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 * 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 or merely acting as a remote for an already-existing
* primary instance. This is implemented by attempting to acquire the * 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. * GDBus.
* *
* Due to the internal architecture of GDBus, method calls can be * Due to the internal architecture of GDBus, method calls can be

View File

@ -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 * of this object (ie: the process exits when the last reference is
* dropped). * dropped).
* *
* The main use for #GApplicationCommandline (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases:
* You can set the <envvar>EDITOR</envvar> 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.
*
* <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
* <para>
* 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.
* </para>
* <programlisting> * <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
@ -60,13 +76,33 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
* </programlisting> * </programlisting>
* </example> * </example>
* *
* <example id="gapplication-example-cmdline2"><title>Complicated commandline handling</title> * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
* <para>
* An example of split commandline handling. Options that start with
* <literal>--local-</literal> are handled locally, all other options are
* passed to the ::command-line handler which runs in the main instance.
* </para>
* <programlisting> * <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include> * </xi:include>
* </programlisting> * </programlisting>
* </example> * </example>
*
* <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
* <para>
* 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.
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
**/ **/
enum enum

View File

@ -90,6 +90,7 @@ SAMPLE_PROGS = \
gapplication-example-open \ gapplication-example-open \
gapplication-example-cmdline \ gapplication-example-cmdline \
gapplication-example-cmdline2 \ gapplication-example-cmdline2 \
gapplication-example-cmdline3 \
gapplication-example-actions \ gapplication-example-actions \
$(NULL) $(NULL)
@ -328,6 +329,9 @@ gapplication_example_cmdline_LDADD = $(progs_ldadd)
gapplication_example_cmdline2_SOURCES = gapplication-example-cmdline2.c gapplication_example_cmdline2_SOURCES = gapplication-example-cmdline2.c
gapplication_example_cmdline2_LDADD = $(progs_ldadd) 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_SOURCES = gapplication-example-actions.c
gapplication_example_actions_LDADD = $(progs_ldadd) gapplication_example_actions_LDADD = $(progs_ldadd)

View File

@ -0,0 +1,65 @@
#include <gio/gio.h>
#include <stdlib.h>
#include <string.h>
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;
}