Tui-Logger Smart Widget Keyboard Shortcuts: Complete Reference Guide

The tui-logger smart widget provides 12 distinct keyboard commands—including arrow keys for navigation, h/f for visibility toggles, and Page Up/Down for history scrolling—that are processed as TuiWidgetEvent variants via the TuiWidgetState::transition() method.

The smart widget in the gin66/tui-logger repository combines a log viewer with an interactive target selector, enabling real-time log level adjustments and filtering directly in the terminal. Mastering these keyboard shortcuts allows developers to build intuitive TUI applications where users can dynamically control log output without leaving the keyboard.

Complete Keyboard Shortcut Reference

The smart widget recognizes the following keyboard inputs, which are documented in the crate’s README section within src/lib.rs【72†L72-L88】:

• h — Toggle the target selector widget between hidden and visible
• f — Switch focus to the currently selected target only
• ↑ (UP) — Move the selection to the previous target in the selector
• ↓ (DOWN) — Move the selection to the next target in the selector
• ← (LEFT) — Decrease the shown log level (one step down)
• → (RIGHT) — Increase the shown log level (one step up)
• - — Decrease the captured log level (one step down)
• + — Increase the captured log level (one step up)
• PageUp — Enter page mode and scroll roughly half a page up in the log history
• PageDown — In page mode only: scroll ten events down in the log history
• Esc — Leave page mode and return to normal scrolling
• Space — Toggle hiding of targets that have their log filter set to Off

Internal Event Handling Architecture

Each keyboard shortcut maps to a variant of the TuiWidgetEvent enum defined in src/widget/inner.rs【45†L45-L58】. When the application receives a key press, it calls TuiWidgetState::transition(event), which forwards the event to TuiWidgetInnerState::transition【83†L83-L138】.

This state machine updates shared internal state including:

• Selection indices for target navigation
• Visibility flags such as hide_target and focus_selected
• Log level thresholds for both shown and captured filters
• Paging pointers like opt_line_pointer_center for history navigation

The smart widget’s render method in src/widget/smart.rs【29†L29-L115】 reads these state values to determine whether to draw the target selector, which log level indicators to highlight, and how to apply paging offsets during terminal drawing.

Implementing Keyboard Navigation in Your Application

To integrate these shortcuts into your terminal application, map your input library’s key events to TuiWidgetEvent variants and pass them to the shared state:

use tui_logger::{TuiWidgetState, TuiWidgetEvent};
use crossterm::event::{KeyCode, KeyEvent};

fn handle_input(state: &TuiWidgetState, key_event: KeyEvent) {
    match key_event.code {
        KeyCode::Char('h') => state.transition(TuiWidgetEvent::HideKey),
        KeyCode::Char('f') => state.transition(TuiWidgetEvent::FocusKey),
        KeyCode::Up       => state.transition(TuiWidgetEvent::UpKey),
        KeyCode::Down     => state.transition(TuiWidgetEvent::DownKey),
        KeyCode::Left     => state.transition(TuiWidgetEvent::LeftKey),
        KeyCode::Right    => state.transition(TuiWidgetEvent::RightKey),
        KeyCode::Char('-')=> state.transition(TuiWidgetEvent::MinusKey),
        KeyCode::Char('+')=> state.transition(TuiWidgetEvent::PlusKey),
        KeyCode::PageUp   => state.transition(TuiWidgetEvent::PrevPageKey),
        KeyCode::PageDown => state.transition(TuiWidgetEvent::NextPageKey),
        KeyCode::Esc      => state.transition(TuiWidgetEvent::EscapeKey),
        KeyCode::Char(' ')=> state.transition(TuiWidgetEvent::SpaceKey),
        _ => {}
    }
}

You can also programmatically simulate key events for testing or automation:

use tui_logger::TuiWidgetEvent::{UpKey, DownKey, LeftKey, RightKey, SpaceKey};

let state = TuiWidgetState::new();
state.transition(UpKey);        // Move selection up
state.transition(DownKey);      // Move selection down
state.transition(LeftKey);      // Decrease shown log level
state.transition(RightKey);     // Increase shown log level
state.transition(SpaceKey);     // Toggle hiding of Off-filtered targets

Summary

• The tui-logger smart widget provides 12 keyboard shortcuts for controlling visibility, navigation, log levels, and history paging.
• All shortcuts are represented by the TuiWidgetEvent enum in src/widget/inner.rs.
• Input handling requires calling TuiWidgetState::transition(), which updates the internal state machine.
• The render method in src/widget/smart.rs reflects these state changes in the terminal interface.
• Application developers must bridge their input library (e.g., crossterm) to the TuiWidgetEvent variants to enable user interaction.

Frequently Asked Questions

What is the difference between "shown" and "captured" log levels?

The shown log level (adjusted with ←/→ arrow keys) controls which severity levels are visible in the widget display, letting you hide debug output without discarding it. The captured log level (adjusted with -/+ keys) controls which records the logger actually processes and stores internally. This dual-filtering system allows you to capture verbose logs for debugging while keeping the display focused on errors.

How does page mode work for scrolling history?

Pressing PageUp enters a frozen page mode that scrolls roughly half a page up through historical log entries. While active, PageDown scrolls ten events downward, and Esc exits page mode to resume live scrolling. This prevents new incoming log messages from interrupting your review of past events.

Can I remap the default keyboard shortcuts?

The current implementation uses fixed key mappings in the TuiWidgetEvent enum. To use different physical keys, map your preferred inputs to the standard TuiWidgetEvent variants in your application’s input handler, as demonstrated in the implementation example above. The library does not currently support runtime configuration of the event variants themselves.

Why does the target selector not appear when the widget first renders?

The target selector starts in a hidden state by default. Press h to toggle its visibility. If the selector appears empty, press Space to ensure targets filtered to Off are not being hidden from the list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}