GNOME Bugzilla – Bug 643468
GApplication docs: Warn that handling "command-line" means manual activating or opening
Last modified: 2011-03-19 12:36:45 UTC
As far as I can tell, when returning TRUE from the "command-line" signal handler, the local instance will then exit, presumably because it means "nothing more whatsoever needs to be done by this instance". But that's not clearly mentioned in the g_application_run() documentation that is mentioned in the signal's documentation: http://library.gnome.org/devel/gio/unstable/GApplication.html#g-application-run I guess that this behaviour should also be mentioned in the documentation for G_APPLICATION_HANDLES_OPEN: http://library.gnome.org/devel/gio/unstable/GApplication.html#G-APPLICATION-HANDLES-OPEN:CAPS and for the "open" signal: http://library.gnome.org/devel/gio/unstable/GApplication.html#GApplication-open because otherwise people will be surprised that the signal is never emitted. This might prevent other signals from being emitted too, so I guess hints should be added to those flags and signals too. I'll get around to improving the documentation myself eventually. I'm just gathering information.
In fact, even when returning FALSE, neither "activate" or "open" seem to be emitted. So maybe I misunderstand this even more.
Are G_APPLICATION_HANDLES_OPEN and G_APPLICATION_HANDLES_COMMAND_LINE mutually exclusive? Maybe, when using G_APPLICATION_HANDLES_COMMAND_LINE, we are meant to get filepath and open it explicitly, via a G_OPTION_ARG_FILENAME or from the GOption "rest arguments"?
The relevant documentation is http://library.gnome.org/devel/gio/2.28/GApplicationCommandLine.html#GApplicationCommandLine.description It explains that the lifecycle of the remote process is tied to the lifecycle of the GApplicationCommandline object that gets passed to the ::command-line handler. I'll add another example that hopefully makes this a little clearer.
To clarify some more things here: The return value of ::command-line is not a boolean. It is an integer that gets used as the exit status of the calling process. About the flags: they are not technically exclusive. Note that the g_application_run() docs only describe the default handler for local_command_line - if you override it, you can do whatever you want. As far as the default handler is concerned, the following is true: If HANDLES_COMMAND_LINE is set, ::command-line is emitted in the primary instance. Otherwise, if there are no cmdline options, ::activate is emitted in the primary instance. If there are cmdline options and HANDLES_OPEN is set, all options are interpreted as filenames, and ::open is emitted in the primary instance. It is an error if there are comdline options and HANDLES_OPEN is not set.
I added another example and some more text.
(In reply to comment #3) > http://library.gnome.org/devel/gio/2.28/GApplicationCommandLine.html#GApplicationCommandLine.description > > It explains that the lifecycle of the remote process is tied to the lifecycle > of the GApplicationCommandline object that gets passed to the ::command-line > handler. > Note that the g_application_run() docs only describe the default handler for local_command_line - if you override it, you can do whatever you want. Yes, actually, the most important thing seems to be that my "command-line" signal handler should call g_application_activate() or g_application_open() because filenames in the command-line won't now be parsed and handled by default. I now have this working in my gtkmm example: http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/application/exampleapplication.cc#n86 However, this is an issue when just handling the "command-line" signal, even when you don't override the local_command_line() vfunc. The g_application_run() documentation, linked to by the "command-line" documentation, only mentions the need default functionality when overriding local_command_line(), not also when handling "command-line": " Otherwise, the default implementation of local_command_line() tries to do a couple of things that are probably reasonable for most applications. First, g_application_register() is called to attempt to register the application. If that works, then the command line arguments are inspected. If no commandline arguments are given, then g_application_activate() is called. If commandline arguments are given and the G_APPLICATION_HANDLES_OPEN flag is set then they are assumed to be filenames and g_application_open() is called. " And, for either case, I can't find an explicit mention of the need to reimplement that default handling if you want it while also parsing additional command-line options. I guess it would be best to just add a hint about this to the documentation for the "command-line" signal itself.
Not 100% sure what you are suggesting here. Maybe we should state more clearly that the default handling in local_command_line only covers two cases: 1. No arguments (ie activate) 2. All arguments are files (ie open) If you need to handle other options, your next best option is to set HANDLE_COMMAND_LINE and handle commandlines in the primary instance. Only if you _need_ to look at commandline options in the launching instance, you should override local_command_line. But really, this is all much too focused on commandline options. One of the goals of the GApplication design is to move the attention off commandline options and towards files and actions...
Oh, I forgot to say: it makes _no_ sense to call activate or open from your command_line handler. Activate, open and command_line are alternative entry points to the primary instance. If you are inside command_line, you are already in the primary instance, no need to activate it again.
> Only if you _need_ to look at commandline options in the launching instance, > you should override local_command_line. My point is that this information is apparently relevant to the "command-line" signal too.
Ok, I tried to add some more
(In reply to comment #8) > Oh, I forgot to say: it makes _no_ sense to call activate or open from your > command_line handler. > > Activate, open and command_line are alternative entry points to the primary > instance. If you are inside command_line, you are already in the primary > instance, no need to activate it again. But it feels like logical API to use. What's the downside? Would it involve D-Bus communication? If so, can't that be avoided by detecting that we are already in the primary instance?