Add a global shortcut portal

[aleixpol]

It's designed so that applications can register actions that can be
triggered globally (i.e. regarless of the system's state, like focus).

WIP because:

• It's untested
• There's no implementation for it
• Needs reviews

Fixes #624

[whot]

fwiw, personally I could really use a few examples here to better understand what the intention is of this portal. I get that it would address the simple "ctrl+c" shortcut type but it seems overspecced for that simple case. And I think it may be underspecced for the more complex cases that require key repeats. So I'm wondering: what are the specific use-cases you are trying to solve here?

[smcv]

I get that it would address the simple "ctrl+c" shortcut type but it seems overspecced for that simple case

My understanding is that this is for global shortcuts that are always active, even while an unrelated application has keyboard focus. Instead of "copy" or "zoom in", think more like "start recording".

While an application has focus, it can receive Ctrl+C (or similar) in the usual X11 or Wayland way, without needing portals.

[jadahl]

Lets say we have an application that can control the sun shade of a physical window, and that it wants to bind the actions "roll up sun shade" and "roll down sun shade" using the global shortcut portal to some two key bindings.

Could you describe step by step how the application does this, when a portal dialog will be presented, and how the application does the second time it launches?

[aleixpol]

Could you describe step by step how the application does this, when a portal dialog will be presented, and how the application does the second time it launches?

app:

void activatedCallback(name)
{
    if (name == "shade-up")
        shade->up();
    else if (name == "shade-down")
        shade->down();
}

request = CreateSession({
    "shade-up", i18n("Rolls the sun shades up"),
    "shade-down", i18n("Rolls the sun shades down")
})

request.exec(); // Wait for it to finish...
session = request.result()["session_handle"];

connect(session.activated, activatedCallback);

if (we really want to make sure the global shortcuts are active) {
    request = ListShortcuts(session);
    request.exec(); // Wait for it to finish...
    shortcuts = request.result(); // [2]
    
    if (shortcuts["shade-up"] == null) {
        request = Bind("shade-up"); // The portal might prompt here [1]
        request.exec(); // Wait for it to finish...
        request.makeSureItDidNotFail();
    }
    if (shortcuts["shade-down"] == null) {
        request = Bind("shade-down"); // The portal might prompt here [1]
        request.exec(); // Wait for it to finish...
        request.makeSureItDidNotFail();
    }
}

// We update the UI for the user to know how to trigger it
{
    request = ListShortcuts(session); // [3]
    request.exec(); // Wait for it to finish...
    shortcuts = request.result();
    
    ui.shadeUpLabel.text = shortcuts["shade-up"]
    ui.shadeDownLabel.text = shortcuts["shade-down"]
}

1. The portal will always be notified and asked to bind so the application can call this again if the binding needs changing.
2. on the second executions the portal should restore the bindings that were initially registered. We could consider including the ListShortcuts output to the CreateSession's request output
3. We call ListShortcuts twice for readability, Bind() does offer this information in the request's output

[GeorgesStavracas]

I have a few comments about the design of the API. None of the C code was reviews, I'll review the implementation once we figure out the D-Bus bits.

Something I'd like us to think through is the security model of this API. The current iteration implies that applications would need to request the same shortcuts on startup, and no permissions are stored anywhere. This can be an annoying behavior. On the other hand, allowing any app to request global shortcuts without any extra check is not ideal either. So the question is: how would we implement apps only requesting permissions once?

[jadahl]

I agree with @GeorgesStavracas that it'd be good to be able to batch multiple Bind requests into a single BindShortcuts as described above.

Thinking more about the permission model would indeed be good. What needs to be ensured is that: applications should not be allowed to arbitrarily bind shortcuts without user consent; at least the API must make sure that a backend can implement such semantics. It'd also be good to allow an application to be able to request new bindings, or change existing ones, thus the initial set of bindings being set up at session construction is a bit awkward.

Given this, maybe we can take inspiration from the screen cast session restore functionality, by making the following changes:

1. Replace the shortcuts parameter in CreateSession with a restore_token string,
2. Add a restore_token to the data passed via the response signal emitted after CreateSession
3. Replace Bind with BindShortcuts to allow for binding in batches (thus setting up multiple bindings in the same dialog)
4. Pass internationalized description that was previously part of the shortcuts parameter in CreateSession together with BindShortcuts

With this, the flow would be altered slightly, but I believe it should be possible to implement the same user interface as you described in the issue:

void activatedCallback(name)
{
    if (name == "shade-up")
        shade->up();
    else if (name == "shade-down")
        shade->down();
}

options = {};
if (has_restore_token)
    options["restore_token"] = get_saved_restore_token();

request = CreateSession(options);

response = request.exec(); // Wait for it to finish...
session = request.result()["session_handle"];

connect(session.activated, activatedCallback);

response_restore_token = response["restore_token"];

app_config_store.store_shortcut_session_token(response_restore_token)

needs_to_bind = False;
existing_bindings = []
if (response_restore_token is null)
    needs_to_bind = True;
else {
    existing_bindings = ListShortcuts(session);
    if (existing_bindings.length < wanted_bindings.length and should_nag_user_about_bindings())
        needs_to_bind = True
}

if (needs_to_bind) {
    new_bindings = wanted_bindings.remove(existing_bindings)
    BindShortcuts(new_bindings); // <--- will show dialog
}

Edit: github decided to treat some key binding as "save" before the comment was ready, should be fixed now.

[GeorgesStavracas]

Another question that just popped up: should this protocol support binding the same shortcut to multiple key combinations?

[jadahl]

Another question that just popped up: should this protocol support binding the same shortcut to multiple key combinations?

Sounds like something an impl backend can do without involving any APIs.

[swick]

Sounds like something an impl backend can do without involving any APIs.

If we want to give apps access to a string which describes what the shortcut is bound to this might not be so straightforward.

[GeorgesStavracas]

Converted to a Draft so no one (read: me) accidentally merges it

[aleixpol]

Thinking more about the permission model would indeed be good. What needs to be ensured is that: applications should not be allowed to arbitrarily bind shortcuts without user consent; at least the API must make sure that a backend can implement such semantics.

There's no way for an app to register here. We have not even specified how that would work. I'm afraid we might be miscommunicating.

It'd also be good to allow an application to be able to request new bindings, or change existing ones, thus the initial set of bindings being set up at session construction is a bit awkward.

It could be nice to show some UI to let the portal handle the UX for all global shortcuts. I wouldn't expect this to be how every app does it though, as I expect apps to want to show their own UI for listing these shortcuts.

Given this, maybe we can take inspiration from the screen cast session restore functionality, by making the following changes:

1. Replace the `shortcuts` parameter in `CreateSession` with a `restore_token` string,
2. Add a `restore_token` to the data passed via the response signal emitted after `CreateSession`
3. Replace `Bind` with `BindShortcuts` to allow for binding in batches (thus setting up multiple bindings in the same dialog)
4. Pass internationalized description that was previously part of the `shortcuts` parameter in `CreateSession` together with `BindShortcuts`

My understanding is that we should keep the shortcuts an app has requested by its name, no need to keep a token. I don't know in which cases we'd consider the application a different one.

In practice, we can consider shortcuts to be static in a specific version of an app and could change between versions but it should only change slightly.

I do want us to be able to offer a UX that doesn't necessarily have to show UI from the portals, as we've seen this lead us to rather awkward workflows with cross-platform apps.

[aleixpol]

Another question that just popped up: should this protocol support binding the same shortcut to multiple key combinations?

You can also give from gnome's portal a description trigger that is Ctrl+A or Meta+Z, this would allow us to make the supported feature set be less tied to the spec.

Edit: description -> trigger

[GeorgesStavracas]

I feel like we're set on a path of confusion with the terminology here. I'd like to propose the following:

• id: unique identifier of a shortcut within the application
• description: user-visible description of the shortcut, ideally explaining what it will do when triggered
• trigger: the key combination that triggers the given shortcut

Objections?

[swick]

I wouldn't expect this to be how every app does it though, as I expect apps to want to show their own UI for listing these shortcuts.

I still don't get how this is supposed to work.

For example if you want to delete a shortcut and the app doesn't delete it but deletes it in its UI you suddenly have a shortcut bound to a trigger which you are not aware of. How does it work if you want to bind multiple triggers? How does it work if you bind triggers which require rich UI? How do you handle conflicts and potential conflicts?

All of that is pretty straightforward if you do all of it in the application (X11 style) or all of it in the system UI (portal backend) but you want some kind of hybrid which makes everything much harder.

[GeorgesStavracas]

I appreciate Apol is still working on the previous round of review, but I had a few comments to flush

[aleixpol]

Did a PoC implementation of the portal.

• https://invent.kde.org/plasma/xdg-desktop-portal-kde/-/merge_requests/80
• https://invent.kde.org/libraries/xdg-portal-test-kde/-/merge_requests/6

[jadahl]

What happens if one tries to bind shortcuts not part of the CreateSession call?

[aleixpol]

It should error out. I am not sure how this is generally communicated, do you know what would be a good example?

[jadahl]

If it's not allowed to bind shortcuts that wasn't specified in CreateSession the documentation should specify that it'll fail. I guess it will via the response signal.

How would an application that doesn't know its wanted global shortcuts immediately add new ones? Does it have to have one session per added binding?

[aleixpol]

It can close the session and start a new one with the previous + the added one. This is how I imagined it at least.

[jadahl]

I see. Re-creating the session is racy; if one triggers a binding right at the time the app decides to recreate the session, it can be lost. Maybe not a big deal since it's very unlikely to happen very often. Then again, could just as well be one session per binding couldn't it?

[aleixpol]

Re-creating the session is racy; if one triggers a binding right at the time the app decides to recreate the session, it can be lost. Maybe not a big deal since it's very unlikely to happen very often.

Correct. It shouldn't happen though during general runtime of the app.

Then again, could just as well be one session per binding couldn't it?

Yes.

[GeorgesStavracas]

@aleixpol i think this PR now needs to update the Meson files too. Shouldn't be hard to add, and won't impact review too much, but I'd appreciate if you could add it too since next xdg-desktop-portal release will be done with Meson 🙂

[aleixpol]

@aleixpol i think this PR now needs to update the Meson files too.

That explains the CI exploding, should be addressed

[GeorgesStavracas]

There still are a few things to correct here, but I think it'll be more productive to do that myself 🙂

[aleixpol]

Glad to see it's in, I'd have expected a PR into this branch but I guess that will work anyway. Thanks, please poke me for the polishes.

[aleixpol]

I apologise for being a bit obtuse. Will a shortcut exclusivity option be addressed in x-d-p, or will this be left up to the backend implementations? With shortcut exclusivity I refer to sending the keys pressed to the focused application as well as the input event for the activated shortcut.

This protocol is only for system-wide shortcuts. As a foscussed application you can always do as you wish with the input you are given.

If there's any public IRC channel to catch up to internal communications that I am unaware of please let me know.

No, all the communication to put this together in this Pull Request.

[RichardFevrier]

Would it be possible with this portal for a third party app (KDE Settings/GNOME Settings/other...) to be able to list and manage all global shortcuts from every app using them?