====== Toolbar, QuickBar & ActionBar ======

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 [[commands|Command]], der Host ordnet die Buttons nach Gruppe und Priorität an, und ''when''-Ausdrücke steuern die Sichtbarkeit.

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

===== Die drei Leistentypen =====

==== Haupt-Toolbar ====

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 [[menus|View-Titelleiste]] platziert werden.

==== QuickBar (Quick Access Bar) ====

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.

==== ActionBar ====

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.

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

<code javascript>
"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"
    }
  ]
}
</code>

| **Feld** | **Pflicht** | **Beschreibung** |
| ''toolbarId'' | ja | Zielleiste: ''"main"'', ''"quickbar"'', ''"actionbar"'' oder eine benutzerdefinierte Id. |
| ''command'' | ja | Referenz auf einen deklarierten [[commands|Command]]. Der Button löst diesen Command aus. |
| ''icon'' | ja | Relativer Pfad zum Button-Icon (SVG oder PNG). Toolbar-Buttons zeigen in der Regel nur das Icon, keinen Text. |
| ''tooltip'' | nein | Tooltip-Text, der beim Überfahren mit der Maus erscheint. Wenn das Feld fehlt, verwendet der Host den Command-Titel. |
| ''when'' | nein | Kontextausdruck für bedingte Sichtbarkeit. Leerer String oder fehlendes Feld bedeutet: immer sichtbar. |

===== Merge-Verfahren =====

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 [[menus|Menüpunkte]]:

  - Buttons mit ''group''-Angabe werden gruppiert (alphabetisch nach Gruppenname)
  - Innerhalb der Gruppe sortiert nach ''order'' (numerisch aufsteigend)
  - 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.

===== Beispiel: Merge aus drei Add-ins =====

**Add-in A (Assets):**
<code javascript>
"toolbar": [
  { "toolbarId": "main", "command": "assets.list", "icon": "...", "group": "modules", "order": 1 }
]
</code>

**Add-in B (Berichte):**
<code javascript>
"toolbar": [
  { "toolbarId": "main", "command": "reports.dashboard", "icon": "...", "group": "modules", "order": 2 }
]
</code>

**Add-in C (Export):**
<code javascript>
"toolbar": [
  { "toolbarId": "main", "command": "export.pdf", "icon": "...", "group": "actions", "order": 1 }
]
</code>

Das Ergebnis in der Haupt-Toolbar:

<code>
[ Export-PDF ]  |  [ Assets-Liste ] [ Berichte-Dashboard ]
   (actions)    |       (modules)
</code>

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

===== Kontextabhängige Buttons =====

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:

<code javascript>
"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"
  }
]
</code>

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.

==== Dynamische Re-Evaluation ====

Der Host wertet ''when''-Ausdrücke auf Toolbar-Buttons **dynamisch** aus — genau wie bei [[menus|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:

  - ''DoActivate'' im Frame setzt den Kontextwert (z.B. ''activeDocument'')
  - Der Host erkennt die Änderung über ''IContextKeyService''
  - ''ReEvaluateToolbarVisibility'' wertet alle ''when''-Klauseln neu aus
  - 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 [[..:sdk:document-frame|TWvdSDocumentFrame]]:

<code pascal>
procedure TAssetEditorFrame.DoActivate;
begin
  FHost.Context.SetContext('activeDocument', 'assets.editor');
end;

procedure TAssetEditorFrame.DoDeactivate;
begin
  FHost.Context.SetContext('activeDocument', '');
end;
</code>

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

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

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

Dynamisch registrierte Buttons werden identisch zu statischen gemergt und dargestellt.

Weiter zu [[sidebarviews|Sidebar-Views]] oder zurück zur [[start|Contributions-Übersicht]].