You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Sources/TUIkit/TUIkit.docc/Articles/KeyboardShortcuts.md
+35Lines changed: 35 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -186,6 +186,39 @@ Dialog(title: "Confirm") {
186
186
}
187
187
```
188
188
189
+
### Changing the built-in quit key
190
+
191
+
The default quit binding is configurable through ``StatusBarState/quitShortcut``:
192
+
193
+
```swift
194
+
@Environment(\.statusBar) privatevar statusBar
195
+
196
+
statusBar.quitShortcut= .escape
197
+
statusBar.quitShortcut= .ctrlQ
198
+
statusBar.quitShortcut=QuitShortcut(
199
+
key: .f12,
200
+
shortcutSymbol: Shortcut.f12,
201
+
label: "exit"
202
+
)
203
+
```
204
+
205
+
This changes both the Layer 4 quit binding and the displayed system item.
206
+
207
+
### Overriding `q` in a local view context
208
+
209
+
A user-defined status bar item with shortcut `q` and an action intercepts the key before the default quit binding runs:
210
+
211
+
```swift
212
+
EditorView()
213
+
.statusBarItems {
214
+
StatusBarItem(shortcut: "q", label: "close") {
215
+
dismissEditor()
216
+
}
217
+
}
218
+
```
219
+
220
+
This is the correct way to repurpose `q` for a specific screen, dialog, or focus section. The matching user item handles the event in Layer 1, so Layer 4's built-in quit binding is never reached.
221
+
189
222
## Status Bar Shortcuts
190
223
191
224
The status bar displays available shortcuts to the user. Use the ``Shortcut`` namespace for consistent, platform-standard symbols:
Copy file name to clipboardExpand all lines: Sources/TUIkit/TUIkit.docc/Articles/StatusBarGuide.md
+89-27Lines changed: 89 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,9 @@ Configure the shortcut bar at the bottom of the terminal.
4
4
5
5
## Overview
6
6
7
-
The status bar is a persistent row at the bottom of the terminal that shows keyboard shortcuts and contextual information. It is always visible and updates every frame.
7
+
The status bar is a row at the bottom of the terminal that shows keyboard shortcuts and contextual information. It updates every frame while it has active items.
8
+
9
+
The status bar is hidden automatically when there are no active user items and no visible system items.
8
10
9
11
TUIkit provides two status bar styles: ``StatusBarStyle/compact`` (single-line, shortcuts only) and ``StatusBarStyle/bordered`` (bordered with title support).
10
12
@@ -25,60 +27,120 @@ VStack {
25
27
Text("My App")
26
28
}
27
29
.statusBarItems {
28
-
StatusBarItem(.character("n"), label: "New") {
30
+
StatusBarItem(shortcut: "n", label: "new") {
29
31
// handle "n" key press
30
32
}
31
-
StatusBarItem(.character("d"), label: "Delete") {
33
+
StatusBarItem(shortcut: "d", label: "delete") {
32
34
// handle "d" key press
33
35
}
34
36
}
35
37
```
36
38
37
39
Items are registered per frame during rendering. When a view is removed from the tree, its items automatically disappear from the status bar.
38
40
39
-
## The Shortcut Enum
41
+
## Shortcut Display Symbols
40
42
41
-
``Shortcut``defines the key trigger for a status bar item:
43
+
Use ``Shortcut``to keep displayed shortcut symbols consistent:
`Shortcut` defines how the item is displayed. If you do not pass `key:`, `StatusBarItem` derives a trigger key from the shortcut string where possible.
53
57
54
58
## Context Stack
55
59
56
-
Status bar items use a **context stack**. When a dialog or menu opens, it can push its own items onto the stack. The status bar always shows the topmost context:
60
+
Status bar items use a **context stack**. Context-specific items can temporarily replace global items, for example while a dialog is visible:
57
61
58
62
```swift
59
-
// Push a new context (e.g. when opening a dialog)
This means the main view's shortcuts are hidden while a modal is active, and automatically restored when it closes.
77
+
The topmost context replaces global user items in the display. System items remain visible unless a user item uses the same shortcut string.
70
78
71
79
## System Items
72
80
73
81
TUIkit registers built-in system items automatically:
74
82
75
83
| Key | Label | Action |
76
84
|-----|-------|--------|
77
-
|`q` / `Ctrl+C`| Quit | Exit the application |
78
-
|`p`| Palette | Cycle to next color palette |
85
+
|`q`| Quit | Exit the application |
79
86
|`a`| Appearance | Cycle to next border appearance |
87
+
|`t`| Theme | Cycle to next color theme |
88
+
89
+
These appear on the right side of the status bar. Only `q quit` is shown by default. Enable `a appearance` and `t theme` with the ``View/statusBarSystemItems(theme:appearance:)`` modifier.
90
+
91
+
### Overriding `q quit`
92
+
93
+
A user-defined status bar item with shortcut `q` overrides the built-in quit binding for that view context:
94
+
95
+
```swift
96
+
EditorView()
97
+
.statusBarItems {
98
+
StatusBarItem(shortcut: "q", label: "close") {
99
+
closeEditor()
100
+
}
101
+
}
102
+
```
103
+
104
+
This works because status bar items with actions are handled before the default quit binding. The built-in `q quit` system item is also removed from the display when a user item uses the same shortcut string.
105
+
106
+
### Changing the global quit shortcut
107
+
108
+
Change the built-in quit key through ``StatusBarState/quitShortcut``:
109
+
110
+
```swift
111
+
@main
112
+
structMyApp: App {
113
+
@Environment(\.statusBar) privatevar statusBar
114
+
115
+
var body: some Scene {
116
+
WindowGroup {
117
+
ContentView()
118
+
}
119
+
.task {
120
+
statusBar.quitShortcut= .escape
121
+
}
122
+
}
123
+
}
124
+
```
125
+
126
+
Available presets include ``QuitShortcut/q``, ``QuitShortcut/escape``, ``QuitShortcut/ctrlQ``, and ``QuitShortcut/ctrlC``. You can also create a fully custom ``QuitShortcut``.
127
+
128
+
### Hiding the status bar completely
129
+
130
+
Hide all system items and do not register any user items:
0 commit comments