DOCSEARCHbyAlgolia
Submit Docs

cursive

repository·main·Indexed 26 days ago

https://github.com/gyscos/cursive

A Text User Interface (TUI) library for Rust designed for ease-of-use, safety, and flexibility. It enables the creation of terminal applications ranging from simple scripts to complex real-time interfaces and games. The ecosystem includes cursive-core for stable third-party library development and cursive-syntect for syntax highlighting using the syntect crate.

Tokens
7.5K
Snippets
18
Records
57
Agent score
88%

What's inside cursive

  2. Set up a new Cursive project

    main

    To start a new Cursive application, create a new Cargo binary project and add cursive to your Cargo.toml dependencies.

    1. Create the project:
    % cargo new --bin cursive_example
    1. Update Cargo.toml:
    [package]
name = "cursive_example"
version = "0.1.0"

[dependencies]
cursive = "*"

  3. Use cursive-core for third-party library development

    main
    When developing third-party libraries or plugins for Cursive, it is recommended to depend directly on cursive-core instead of the main cursive crate. This helps avoid unnecessary semver breaking updates, as cursive-core is more stable and contains the core definitions of the framework, excluding the backends.

  4. Manage UI layers with pop_layer and add_layer

    main
    To navigate between different screens or popups, use Cursive::pop_layer() to remove the current top-most layer and Cursive::add_layer() to add a new one. This is the standard way to implement transitions, such as moving from a question dialog to a results dialog.

  5. Create a basic Cursive application

    main

    A Cursive application requires a root object (created via cursive::default()) to manage the event loop and layers. You build interfaces by adding layers (like Dialog) to this root.

    In the example below, we create a dialog containing a TextView and a button that calls siv.quit() when clicked. Finally, siv.run() is called to start the application's event loop.

    use cursive::views::{Dialog, TextView};

fn main() {
    // Creates the cursive root - required for every application.
    let mut siv = cursive::default();

    // Creates a dialog with a single "Quit" button
    siv.add_layer(Dialog::around(TextView::new("Hello Dialog!"))
                         .title("Cursive")
                         .button("Quit", |s| s.quit()));

    // Starts the event loop.
    siv.run();
}

  7. Initialize and run a Cursive application

    main

    A Cursive application typically follows three phases centered around the Cursive root object:

    1. Create a Cursive object using cursive::default().
    2. Configure the object (adding callbacks, layers, etc.).
    3. Run the object using .run().

    Basic lifecycle example:

    fn main() {
	let mut siv = cursive::default();
	siv.run();
}
    fn main() {
	let mut siv = cursive::default();

	siv.run();
}

  8. Install Cursive

    main

    To use Cursive in your Rust project, add it to your Cargo.toml dependencies. You can use the stable version from crates.io or the latest version from the GitHub repository.

    Using crates.io (Recommended)

    [dependencies]
cursive = "0.21"

    Using the latest git version

    [dependencies]
cursive = { git = "https://github.com/gyscos/cursive" }
    [dependencies]
cursive = "0.21"

  9. Implement scrolling for a custom view

    main

    To add scrolling capabilities to a custom view, embed scroll::Core in your struct and implement the scroll::Scroller trait. You can use the cursive_core::impl_scroller! macro to simplify the implementation.

    Once implemented, you must delegate the standard View trait methods (on_event, important_area, layout, required_size, and draw) to the provided scroll helper functions to ensure the scrolling logic (like viewport calculation and event handling) is correctly applied.

    use cursive_core::event::{Event, EventResult};
use cursive_core::view::{View, scroll};
use cursive_core::{Printer, Rect, Vec2};

struct MyView {
    core: scroll::Core,
}

// Use the macro to implement Scroller for MyView using its core field
cursive_core::impl_scroller!(MyView::core);

impl MyView {
    fn inner_on_event(&mut self, event: Event) -> EventResult {
        EventResult::Ignored
    }

    fn inner_important_area(&self, size: Vec2) -> Rect {
        Rect::from_size((0, 0), size)
    }
}

impl View for MyView {
    fn draw(&self, _printer: &Printer) {}
    fn on_event(&mut self, event: Event) -> EventResult {
        // Delegate event handling to the scroll module
        scroll::on_event(
            self,
            event,
            Self::inner_on_event,
            Self::inner_important_area,
        )
    }
}

  11. Configure log levels via environment variables

    main

    You can configure logging levels without changing code by using environment variables. Call set_filter_levels_from_env() before init() to apply these settings:

    • RUST_LOG: Sets both internal (cursive-specific) and external log levels to the specified value.
    • CURSIVE_LOG: Sets only the internal log level. This takes precedence over RUST_LOG for internal logs.

    Example values for the variables include trace, debug, info, warn, or error.

  12. Initialize the Cursive logger

    main
    To enable logging within a Cursive application, call init(). This sets up the global CursiveLogger and configures the log crate to use it. Note that this will panic if a logger has already been set. Once initialized, you can view logs using a DebugView or by calling Cursive::toggle_debug_console().