* 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,
* 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
* 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 <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>
+ * <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>
* <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>
* </programlisting>
* </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>
* <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:include>
* </programlisting>
* </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
gapplication-example-open \
gapplication-example-cmdline \
gapplication-example-cmdline2 \
+ gapplication-example-cmdline3 \
gapplication-example-actions \
$(NULL)
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)
--- /dev/null
+#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;
+}