# Commands
Commands are the typed kind: `:quit`, `:n`, `go to notes`. You register a name
with aliases, the user types a string, and the runtime resolves it (by prefix)
to one of your actions.
The crate gives you the *resolver*. It does **not** give you a command palette —
the text box, the cursor, the open/close state are ordinary app state you own
and render. The `full` example builds a complete `:`-style palette this way in
about 30 lines.
## Registering commands
On the builder, `.command(name, aliases, action)`:
```rust
TuiPages::builder(View::Home)
.command("Go to Home", ["h", "home"], Action::GotoHome)
.command("Go to Notes", ["n", "notes"], Action::GotoNotes)
.command("Quit", ["q", "quit"], Action::Quit)
```
The first argument is a display name (shown in hints); the rest are the aliases
the user can type. Matching is by prefix, so `not` resolves to `notes`.
## Submitting input
When the user confirms their typed string, hand it to `submit_command`. It
resolves and runs the action exactly like a key binding would — including
applying any effects and setting `quit_requested`:
```rust
let quit = tui.submit_command(&input, state)?.quit_requested;
```
The returned `TuiPagesOutput::status` tells you what happened:
```rust
pub enum TuiPagesStatus<A> {
ActionHandled, // resolved and ran
CommandIncomplete(Vec<CommandHint>), // a prefix of several commands
CommandUnknown, // no match
CommandEmpty, // empty input
// ...
}
```
## A palette is just app state
The runtime owns no palette. You own a flag and a string, open it on a key, feed
keystrokes to your string, and call `submit_command` on Enter. This is the whole
palette loop from the `full` example:
```rust
// State you own:
// palette_open: bool,
// palette_input: String,
if state.palette_open {
match key.code {
KeyCode::Enter => {
let input = state.palette_input.clone();
let quit = tui.submit_command(&input, state)?.quit_requested;
close_palette(tui, state);
if quit { return Ok(()); }
}
KeyCode::Esc => close_palette(tui, state),
KeyCode::Backspace => { state.palette_input.pop(); }
KeyCode::Char(c) => state.palette_input.push(c),
_ => {}
}
continue; // palette swallows the key; don't fall through to handle_key
}
```
Opening it is an action that sets the flag and (optionally) opens an overlay
focus target so your renderer knows to draw the bar:
```rust
Action::OpenPalette => {
state.palette_open = true;
state.palette_input.clear();
ActionOutcome::effect(TuiEffect::Focus(FocusIntent::Open(
FocusTarget::Overlay(Overlay::CommandBar),
)))
}
```
Closing it clears your state and the overlay:
```rust
fn close_palette(tui: &mut App, state: &mut State) {
state.palette_open = false;
state.palette_input.clear();
tui.focus.clear_overlay();
}
```
## Live hints while typing
To show completions as the user types, query the resolver directly. `tui.commands`
is the public `CommandResolver`:
```rust
match tui.commands.process(&state.palette_input) {
CommandResponse::Incomplete(hints) => show(hints), // Vec<CommandHint>
CommandResponse::Execute(_) => {} // a full match exists
CommandResponse::Unknown => show_error(),
CommandResponse::Empty => {}
}
```
Each `CommandHint` is `{ alias: String, action_name: String }` — the alias to
complete to, and its display name.
The resolution timeout (for multi-step command states) defaults to 1000ms and is
configurable with `.command_timeout_ms(ms)` on the builder.