[neomutt-devel] Key Bindings

[Richard Russon]

# Key Handling Refactor - What's New

NeoMutt's key handling code (`km_dokey()`) has been rebuilt from the
ground up.  The result: **multi-key bindings finally work properly**, you
get real-time feedback as you type them, and overlapping prefixes (like
`a` vs `ab`) are no longer a problem.

Here's what changed and why you should care.

---

## Multi-key bindings just work

Previously, if you bound both `a` and `ab` in the same menu, NeoMutt
would warn you and the shorter binding would block the longer one.
That limitation is gone.

```neomuttrc
bind index a  next-entry
bind index ab previous-entry   # this was impossible before!
```

NeoMutt now uses a **state machine** internally to collect keystrokes
and match them against your bindings.  It waits a short time after a
partial match to see if more keys are coming.  If nothing arrives, it
fires the shortest complete match.

## Two new Config Options

You can tune the timing to your taste:

- `$key_timeout_idle`    1000 ms
  How long NeoMutt waits for the *first* keypress before doing housekeeping
  (e.g. checking for new mail).

- `$key_timeout_partial` 700 ms
  How long NeoMutt waits for *more* keys after a partial match
  (e.g. you typed `a` and `ab` also exists).

Both accept values between 50 and 10 000 ms.
Lower values feel snappier; higher values give you more time to complete a sequence.

## Live key-progress indicator

A tiny **Utility Window** now appears at the bottom-right of the screen
while you're mid-sequence.  It shows the keys you've typed so far, so
you always know where you are in a multi-key binding.  When the sequence
resolves (or times out), the indicator disappears - zero screen space
when you don't need it.

## `<jump>` is Supercharged

Historically, the `<jump>` function was triggered by the digits 0-9.
It would open a prompt and you could type in a row number.

Now, typed _digits_ become part of a **repeat-count**.
Then you can trigger the movement with either `<jump>` or `<Enter>`.

- `<jump>` - prompts you for a number, then jumps
- `42<jump>` - jumps straight to entry 42
- `42<Enter>` - same thing

The quicker among you will realise the potential of the repeat-count!
(more coming soon)

## Under the Bonnet

- `mutt_getch()` gained a configurable timeout parameter.
- `struct KeyEvent` carries a `count` field for repeat prefixes.
- A new notification type (`NT_KEY_PROGRESS`) lets observers (like the
  Utility Window) react to partially typed sequences.
- The GUI reflow logic now clamps allocations to available screen space,
  preventing layout glitches with the new Bottom Bar container.

---

All in all, NeoMutt's key handling is now more flexible, more
transparent, and a lot less surprising.  Enjoy your multi-key bindings!

Cheers,
    FlatCap / Rich
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://mailman.neomutt.org/pipermail/neomutt-devel-neomutt.org/attachments/20260423/39ee1d4e/attachment.sig>