hi Alex, On Tue, Nov 12, 2013, at 13:35, Alex Merry wrote: > David suggested I direct questions about this spec to you.
The xdg list is usually a better place for these types of discussions, for future reference. I'm going to cc: the list into this discussion because there are some details of future plans below that I think might be interesting to everyone. > Firstly, ActivateAction has a parameter named "parameter" that takes an > "av". A comment in the KDE implementation of this interface > (presumeably written by David) says that the "av" type is a workaround > for the lack of a maybe type, but nothing there or in the spec says what > this parameter is to be used for. This makes writing API docs for our > implementation a bit tricky :-) A bit more explanation on the comment first: GVariant is a type system inside of GLib that is extremely similar to D-Bus except that it has a couple of extensions. The most notable one is that it introduces the idea of a maybe type -- you can have the type "ms" that it either containing a string, or "none" (ie: NULL equivalent). You can apply this to any type. D-Bus lacks this type (despite attempts to introduce it multiple times) so there is a common trick to use an array as a "fake maybe". An empty array is equivalent to the NULL case and an array with 1 item in it is equal to the case where that item is the item of interest. If the array has more than 1 item, the extra items are ignored. As for explaining the field itself: in GLib, actions take GVariant parameters on activation. See https://developer.gnome.org/gio/2.36/GAction.html#g-action-activate for the API. This can be NULL (which is the empty-array case on the wire protocol) or it can be any D-Bus value (which is the one-item-in-array case). It's simply extra information to the action invocation. Currently, ActivateAction in the org.freedesktop.Application interface is only used for launching "Additional application actions" from desktop files in the DBusActivatable=true case, as described here: http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extra-actions In this case, the parameter is always NULL (ie: empty array). The reason that we introduced the parameter field was a bit of foresight into what we would do next. At the next freedesktop Sprint (and this is probably interesting news to you too, David), we plan to propose standardising something like the following: https://wiki.gnome.org/GNotification which we have implemented in GLib and gnome-shell. The main change here vs. the existing specification is that notifications persist after the application quits and are capable of reactivating the application when clicked on. This means that your SMS or email app can send a "you have a new message" notification after checking in the background and then exit, to be restarted when the user clicks on the message notification to view it. The main difficulty here is that when the app is cleanly restarted, it will not have any particular notification objects around on which to send "response" signals. As such, we decided that the easiest thing to do would be to route responses via application actions. So, I might send a notification like so: /---------------------------------------(x)\ | You have a new message | | | | Congratuations! Your email won the | | internet lottery for $10000000!! | | | | ( Reply ) ( Mark as spam ) | \------------------------------------------/ with the default "click on notification" action being to view the message. In order for this to work, we expect that people would add the following actions on their application: - app.reply-to-message - app.mark-message-as-spam - app.view-message and each of them would take a message ID string as an action parameter. Let's assume our message above has ID msgid2384290. We'd then setup the notification with the following: - default action: "app.view-message::msgid2384290" - action for reply button: "app.reply-to-message::msgid2384290" - action for spam button: "app.mark-message-as-spam::msgid2384290" Where "app.action::detail" is GLib's internal "detailed action format" (which is not part of any spec we intend to propose). It's a convenient way of indicating an action name along with a parameter. The "app." is an indication that this is an action defined on the application, and we do intend for this to be part of the spec (and it is, as we have implemented it in GNOME). Now let's assume that the mail program sends that notification and then exits. The user returns to their computer and sees the notification and clicks "spam". The email program is not running, but fortunately it's DBusActivatable using the org.freedesktop.Application interface. We therefore can send a message as follows to the well-known name of the app (let's say 'org.gnome.email'): to: org.gnome.email /org/gnome/email method: org.freedesktop.Application.ActivateAction parameters: ('mark-message-as-spam', [<'msgid2384290'>], {'desktop-startup-id': <'_TIME2398420'>}) ((where <> is the GVariant format for denoting the wrapping of the 'v' type in D-Bus and the 'desktop-startup-id' thing is the blob described in http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt as http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus specifies sending). Because the app is DBusActivatable, the application will now be D-Bus activated by the system. It will not, however, receive the normal Activate signal that would typically be associated with such an activation (because nobody sent it). It will receive the above action activation instead. It can mark the message as spam and exit again, without ever having shown a window. Of course, if the user had selected to "reply" or "view" (default action) instead, then the compose or messsage viewer windows would have been shown instead (and again note, the main message list window need not be shown for these cases) -- no 'Activate' signal was received by the app. the TL;DR: of all of this is that we have some future stuff that we plan to put on track for freedesktop.org standardisation that will depend on actions having parameters routed through to them. As such, I recommend carrying this parameter through on your APIs if at all possible. > Secondly, we our implementation also supports enforcing an "only one > instance" rule for the application. Currently, this just calls > Activate() if the executable is run a second time (ie: the relevant > D-Bus name is taken), but this discards any command-line arguments. Our > plan is to add a CommandLine method (on the same object, but a different > interface, such as org.kde.Application) that takes a list of > command-line arguments. Judging from the GApplication API docs, this > looks similar to what you do in glib. Do you have any "lessons learnt" > that we should take into account? In general, I'd do my best to convince people to avoid implementing a CommandLine handler. Commandline arguments generally fall (widely) into the following: - customising global behaviour of the app (like enabling debug output, etc) - filenames or URIs to open - special modes of starting the app, like 'myemailapp --compose' or so For the first case, you're going to have a bad time. If you manage to set these type of 'global state arguments' on the first run then you're OK but any future runs will probably ignore them. Not much you can do about that, and I believe that these sorts of arguments are probably slightly evil in "only one instance" apps for the above reason. I like environment variables for this sort of thing. If you insist on processing these as commandline arguments (as many do) then I guess the best way is to only expect them to work in the first instance that you run, in which case they need no special treatment. The second case (filenames) is ideally handled by converting them into invocations of the 'Open' D-Bus method on the org.freedesktop.Application API. GApplication does this as a matter of default behaviour in applications that support opening files. In the third case, for actions like --compose, I believe the best thing to do is to convert these into action activations. In essence, send a "compose-message" action to the already-running instance, causing it to pop up a compose window. In the case that you have an argument like "--compose-to [email protected]" then "[email protected]" could be a string-valued parameter to an action called "compose-to" (which is another reason you may want to support parameters to action activations, as discussed above). The one case where I believe that CommandLine is truly useful is for programs that have existing well-established conventions of how they behave when invoked from the commandline. My absolute favourite example here is a GUI-based text editor used as defined in the EDITOR environment variable. When I do 'git commit', git has particular expectations about how the command will behave. In this particular case, it expects that the command exits when the editing is done. This poses problems for applications in a "only one instance" world. What if the invocation is the second invocation? Probably then the executable will send the message and quit right away and git will complain about "you didn't make any changes -- aborting the commit". What about if it is the first instance, but in the middle of writing my commit message, I want to look at another file? Then the editor will not exit until I've closed both files. This is one of the reasons I've pushed towards DBusActivatable applications. In any case, invocation of the editor on the commandline will be a small simple program that sends a D-Bus message causing activation of the "full" program remotely. The commandline portion of the program can now exit freely. That said, it should only exit when the user has closed the tab that contains the file being edited. Therefore, your CommandLine mechanism should probably have some way of supporting controlling when the remote instance will exit. Your commandline mechanism should also contain support for seeing which environment variables were set in the remote invocation, and definitely should have support for querying the cwd on the other side (since probably users expect to be able to pass paths to their editor relative to their cwd and have them resolved properly). I recommend a convenience API for "turn this commandline argument into an absolute path, according to the cwd on the remote side", since very many apps will want this. Your commandline mechanism may also want to support forwarding of stdin/stdout/stderr (or even other file descriptors) from the remote side, because your user may expect that your editor will be able to open "-". There are quite a lot of complicated considerations here. The org.freedesktop.Application interface was originally only designed to support launching desktop files (with an eye towards notifications coming down the pipe soon). These two facts together caused me to keep CommandLine out of the spec. I still think that there would be little to no value to adding it because each side will have their own separate library to support applications that want to do this and there will probably be no system-level component that has to interoperate with applications in this way -- this protocol will always be between an application and itself (ie: the 'service' and the 'launcher' sides). The one thing that gives me pause here is that we recently introduced a gapplication(1) commandline tool that supports sending activate/open/activateaction to the org.freedesktop.Application interface. We have some vague plans to add support for sending CommandLine invocations, as well, using the GLib style. It would certainly be nice if this tool could interoperate with KDE applications for CommandLine invocations and it would also be nice to keep the tool "pure" in terms of only speaking freedesktop-specified interfaces, but I'm not sure that there is enough value here to bother dragging all of the above mess into a freedesktop-specified standard (with all the stability requirements, etc). In any case, I thank you for your interest in all of this and wish you luck with the implementation. I'm glad to see that KDE is going to be supporting all of this soon and I'm very happy to continue answering any questions you have about it. Cheers _______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
