Can a few UIControls be combined in a Window and handle shared KeyBindings?

[4l1fe]

I'm creating a simple TUI that helps me change a terminal theme where i can interactively select a theme name from a list using FormatedTextControl and attached keybindings.

Currently, i'm trying to find a way to add BufferControl to the same window where the text control is to type a word for fuzzy finding the nearest lines in the theme names list for further selection.

However, i'm unsure whether it's possible to contain both controls in one window and handle one set of KeyBidings that allows me to type in arbitrary words for fuzzy finding and select the found lines in the list using arrows keys or ctrl + <key> combinations.

What is a proper way to combine these two controls and smoothly switch a focus between them as if they were a single control?

[TayfurYldz]

A Window is the wrong level to combine these: it owns exactly one UIControl. So a FormattedTextControl and a BufferControl should normally live in separate Window objects, with an HSplit/VSplit composing those windows.

You can still make them behave as one logical widget. Put the shared key bindings on the parent split (or application), and switch focus explicitly with event.app.layout.focus(...). prompt_toolkit's own dialogs use this pattern; focus navigation is also exposed through focus_next / focus_previous.

For fuzzy search specifically, I would keep the editable query in a real Buffer/BufferControl, and keep the result list in a FormattedTextControl. When the buffer changes, recompute the filtered rows and invalidate/redraw the application. Then your shared bindings can decide based on focus/state whether arrows move the selected result or edit/navigate the input.

Conceptually:

query_window = Window(BufferControl(buffer=query))
results_window = Window(FormattedTextControl(render_results, key_bindings=result_kb))

root = HSplit([results_window, query_window], key_bindings=shared_kb)

A binding that starts search mode can focus query_window; Enter/Escape can focus results_window again. If you want typing to always feed the query while the list visually remains selected, you can instead keep focus on the BufferControl and handle list navigation through application-level bindings—the visible focus and selected-row styling don't have to be the same concept.

Trying to put both controls in one Window would require writing a custom UIControl that implements both editing and list rendering itself. That's possible, but for this use case it gives up BufferControl's existing editing machinery for little benefit.

[TayfurYldz]

A Window can only have one UIControl, so I would not try to put a FormattedTextControl and a BufferControl in the same Window.

Instead, make them two windows in one container (typically an HSplit for a list with an input line below it), and let the Layout manage focus. This is the same composition model used by prompt_toolkit's full-screen examples: each buffer/control owns a window, while containers arrange those windows.

For a fuzzy-filter UI, an especially simple structure is:

query = Buffer()
query_window = Window(BufferControl(buffer=query), height=1)
list_window = Window(FormattedTextControl(get_items, focusable=True))

root = HSplit([list_window, query_window])
layout = Layout(root, focused_element=list_window)

Then keep the key bindings at the application level when they are meant to work in both places. A binding can inspect event.app.layout.current_window, or use filters such as has_focus(query_window), to decide whether arrows move the list selection or the input cursor. To enter search mode, call event.app.layout.focus(query_window); to return to list navigation, focus list_window.

You may not need to switch focus for every printable character, though. If the desired UX is "typing always updates the fuzzy query while arrows always navigate the list", an application-level printable-character binding can update the query buffer directly while leaving focus on the list. That often feels more like one compound control and avoids cursor/focus churn.

If the behavior is specifically search rather than an arbitrary editable field, also look at SearchToolbar: it already packages a search buffer/control, conditional visibility, and focus transitions. But for fuzzy matching with custom result selection, the two-window HSplit plus shared application bindings is the more flexible model.