Die Shell stellt mehrere Leistentypen bereit, in die Add-ins Buttons einbringen können. Jede Leiste hat einen eigenen Zweck und ein eigenes Merge-Verhalten, aber alle verwenden dasselbe Grundprinzip: Ein Button verweist auf einen Command, der Host ordnet die Buttons nach Gruppe und Priorität an, und when-Ausdrücke steuern die Sichtbarkeit.

Zurück zur Contributions-Übersicht oder zur Hauptübersicht.

Die Haupt-Toolbar ist die primäre Leiste unterhalb der Menüleiste. Sie enthält die am häufigsten verwendeten Aktionen. Add-ins platzieren Buttons hier über die toolbarId „main“.

Die Haupt-Toolbar ist für globale, kontextunabhängige Aktionen gedacht: Dokument öffnen, Speichern, Rückgängig. Aktionen, die nur in bestimmten Kontexten relevant sind, sollten stattdessen in der ActionBar oder in der View-Titelleiste platziert werden.

Die QuickBar ist eine schmale Leiste mit häufig genutzten Schnellzugriffen. Sie enthält typischerweise kompaktere Buttons ohne Text — nur Icons. Add-ins platzieren Buttons hier über toolbarId „quickbar“.

Der Benutzer kann die QuickBar anpassen: Buttons hinzufügen, entfernen und umsortieren. Der Host speichert diese Anpassungen in den Benutzer-Einstellungen. Die vom Add-in deklarierten Buttons sind die Standardvorgabe, die der Benutzer überschreiben kann.

Die ActionBar erscheint kontextabhängig, typischerweise am oberen Rand eines Dokument-Tabs oder einer View. Sie zeigt Aktionen, die zum gerade aktiven Inhalt passen. Add-ins platzieren Buttons hier über toolbarId „actionbar“.

Der Vorteil der ActionBar gegenüber der Haupt-Toolbar: Buttons in der ActionBar erscheinen nur, wenn ihr Kontext aktiv ist. Das hält die Oberfläche aufgeräumt. Wenn der Benutzer zu einem anderen Dokumenttyp wechselt, verschwinden die ActionBar-Buttons des vorherigen Typs und die des neuen erscheinen.

"contributes": {
  "toolbar": [
    {
      "toolbarId": "main",
      "command": "assets.list",
      "icon": "media/asset-list.svg",
      "tooltip": "Anlageliste öffnen",
      "when": ""
    },
    {
      "toolbarId": "quickbar",
      "command": "assets.open",
      "icon": "media/asset-open.svg",
      "tooltip": "Anlage öffnen",
      "when": ""
    },
    {
      "toolbarId": "actionbar",
      "command": "assets.save",
      "icon": "media/save.svg",
      "tooltip": "Anlage speichern",
      "when": "activeDocument == assets.editor"
    }
  ]
}

Der Host sammelt alle Toolbar-Contributions aus allen installierten Add-ins und gruppiert sie nach toolbarId. Innerhalb jeder Toolbar werden die Buttons nach denselben Regeln sortiert wie Menüpunkte:

1. Buttons mit group-Angabe werden gruppiert (alphabetisch nach Gruppenname)
2. Innerhalb der Gruppe sortiert nach order (numerisch aufsteigend)
3. Zwischen Gruppen fügt der Host einen visuellen Trenner ein (schmaler Strich oder Abstand)

Wenn kein group-Feld angegeben ist, verwendet der Host eine Standardgruppe. Buttons ohne explizite Gruppe landen alle in derselben Sektion.

Add-in A (Assets):

"toolbar": [
  { "toolbarId": "main", "command": "assets.list", "icon": "...", "group": "modules", "order": 1 }
]

Add-in B (Berichte):

"toolbar": [
  { "toolbarId": "main", "command": "reports.dashboard", "icon": "...", "group": "modules", "order": 2 }
]

Add-in C (Export):

"toolbar": [
  { "toolbarId": "main", "command": "export.pdf", "icon": "...", "group": "actions", "order": 1 }
]

Das Ergebnis in der Haupt-Toolbar:

[ Export-PDF ]  |  [ Assets-Liste ] [ Berichte-Dashboard ]
   (actions)    |       (modules)

Die actions-Gruppe steht vor modules (alphabetisch). Innerhalb der modules-Gruppe stehen Assets vor Berichte (order 1 < 2). Der vertikale Strich ist der Gruppentrenner.

Die ActionBar ist besonders nützlich für kontextabhängige Aktionen. Der when-Ausdruck stellt sicher, dass Buttons nur erscheinen, wenn ihr Kontext aktiv ist:

"toolbar": [
  {
    "toolbarId": "actionbar",
    "command": "assets.save",
    "icon": "media/save.svg",
    "when": "activeDocument == assets.editor && isDirty"
  },
  {
    "toolbarId": "actionbar",
    "command": "assets.print",
    "icon": "media/print.svg",
    "when": "activeDocument == assets.editor"
  }
]

In diesem Beispiel erscheint der Speichern-Button nur, wenn ein Asset-Editor aktiv ist und ungespeicherte Änderungen vorliegen. Der Drucken-Button erscheint immer, wenn ein Asset-Editor aktiv ist. Wechselt der Benutzer zu einem anderen Dokumenttyp, verschwinden beide Buttons.

Der Host wertet when-Ausdrücke auf Toolbar-Buttons dynamisch aus — genau wie bei Menüpunkten. Sobald sich ein Kontextwert ändert (z.B. beim Tab-Wechsel), durchläuft der Host alle Toolbar-Buttons mit when-Klausel und aktualisiert deren Sichtbarkeit sofort. Buttons ohne when-Klausel bleiben immer sichtbar.

Das bedeutet: Wenn zwei Add-ins Toolbar-Buttons für verschiedene Dokumenttypen deklarieren, sieht der Benutzer nur die Buttons, die zum gerade aktiven Dokument passen. Beim Tab-Wechsel verschwinden die Buttons des vorherigen Typs und die des neuen erscheinen — ohne Flackern und ohne dass das Add-in aktiv eingreifen muss.

Die Kette ist:

1. DoActivate im Frame setzt den Kontextwert (z.B. activeDocument)
2. Der Host erkennt die Änderung über IContextKeyService
3. ReEvaluateToolbarVisibility wertet alle when-Klauseln neu aus
4. Buttons mit Visible := False werden ausgeblendet, das Layout wird aktualisiert

Das Add-in muss dafür den Kontextwert activeDocument setzen. Das geschieht typischerweise in der DoActivate-Methode des TWvdSDocumentFrame:

procedure TAssetEditorFrame.DoActivate;
begin
  FHost.Context.SetContext('activeDocument', 'assets.editor');
end;
 
procedure TAssetEditorFrame.DoDeactivate;
begin
  FHost.Context.SetContext('activeDocument', '');
end;

Für dynamische Szenarien bietet IToolbarService die Laufzeit-Registrierung:

AContext.Subscribe(
  FHost.Toolbar.AddToolbarItem('actionbar', 'assets.custom-action',
    'media/custom.svg', 'Benutzerdefinierte Aktion',
    'activeDocument == assets.editor')
);

Dynamisch registrierte Buttons werden identisch zu statischen gemergt und dargestellt.

Weiter zu Sidebar-Views oder zurück zur Contributions-Übersicht.