====== Keybindings ======

Tastenkürzel verbinden eine Tastenkombination mit einem [[commands|Command]]. Der Benutzer drückt die Tasten, der Host löst den zugehörigen Command aus. Wie bei [[menus|Menüs]] und [[toolbar|Toolbar-Buttons]] kann ein ''when''-Ausdruck die Gültigkeit auf bestimmte Kontexte einschränken.

Zurück zur [[start|Contributions-Übersicht]] oder zur [[..:start|Hauptübersicht]].

===== Manifest-Deklaration =====

<code javascript>
"contributes": {
  "keybindings": [
    {
      "command": "assets.list",
      "key": "Ctrl+Shift+A",
      "mac": "Cmd+Shift+A",
      "when": ""
    },
    {
      "command": "assets.save",
      "key": "Ctrl+S",
      "when": "activeDocument == assets.editor && isDirty"
    }
  ]
}
</code>

| **Feld** | **Pflicht** | **Beschreibung** |
| ''command'' | ja | Referenz auf den auszuführenden [[commands|Command]]. |
| ''key'' | ja | Tastenkombination für Windows und Linux (z.B. ''Ctrl+Shift+A''). |
| ''mac'' | nein | Alternative Kombination für macOS. Wenn das Feld fehlt, wird ''key'' auch auf macOS verwendet. |
| ''when'' | nein | Kontextausdruck für bedingte Gültigkeit. Das Tastenkürzel wird nur ausgewertet, wenn der Ausdruck wahr ist. |

===== Tastenkombinationen =====

Tastenkombinationen werden als String angegeben. Die Notation folgt einem einfachen Schema:

| **Modifier** | **Windows/Linux** | **macOS** |
| Steuerung | ''Ctrl'' | ''Cmd'' |
| Umschalt | ''Shift'' | ''Shift'' |
| Alt | ''Alt'' | ''Alt'' |

Modifier werden mit ''+'' verkettet, gefolgt von der Taste:

  * ''Ctrl+S'' — Steuerung + S
  * ''Ctrl+Shift+P'' — Steuerung + Umschalt + P
  * ''Alt+F4'' — Alt + F4
  * ''F5'' — Funktionstaste ohne Modifier

Der Host wandelt den String intern in einen ''TShortCut''-Wert um. Ungültige Kombinationen werden beim Laden gemeldet und ignoriert.

===== Kontextbezogene Kürzel =====

Der ''when''-Ausdruck ermöglicht es, dass dasselbe Tastenkürzel in verschiedenen Kontexten verschiedene Commands auslöst:

<code javascript>
"keybindings": [
  {
    "command": "assets.save",
    "key": "Ctrl+S",
    "when": "activeDocument == assets.editor"
  },
  {
    "command": "reports.save",
    "key": "Ctrl+S",
    "when": "activeDocument == reports.editor"
  }
]
</code>

In diesem Beispiel löst ''Ctrl+S'' den Speichern-Command des jeweils aktiven Editors aus. Wenn der Asset-Editor aktiv ist, wird ''assets.save'' ausgeführt; wenn der Berichts-Editor aktiv ist, wird ''reports.save'' ausgeführt. Ohne ''when''-Ausdruck würde der Host bei Konflikten den zuletzt registrierten Command verwenden.

===== Konflikterkennung =====

Wenn zwei Add-ins dasselbe Tastenkürzel ohne ''when''-Ausdruck registrieren, entsteht ein Konflikt. Der Host löst Konflikte nach dem First-Registered-Wins-Prinzip: Das zuerst registrierte Kürzel gewinnt, das zweite wird ignoriert und im Log protokolliert. Um Konflikte zu vermeiden, sollten Add-ins möglichst spezifische ''when''-Ausdrücke verwenden oder ungewöhnliche Tastenkombinationen wählen.

===== Programmatische Registrierung =====

Wie bei allen Contribution-Typen ist die deklarative Registrierung im [[..:manifest|Manifest]] der bevorzugte Weg. Für dynamische Szenarien steht ''IKeybindingService'' bereit:

<code pascal>
AContext.Subscribe(
  FHost.Keybindings.RegisterKeybinding('Ctrl+Shift+R',
    'assets.refresh', 'activeDocument == assets.editor')
);
</code>

Weiter zum [[..:skin-contract|Skin-Vertrag]] oder zurück zur [[start|Contributions-Übersicht]].