• Cartographer-rs
  • Example
  • How to Use
    • Adding it to your project dependencies
    • Creating a menu!
    • Serving your menu
    • Configuration

Cartographer-rs

Cartographer is a small library using Console and macros to bring “just add water” TUI menus to your programs.

Utilizing the power of macros, you can create an interactive menu in less than 10 lines of code.

The main reason I created this crate, is that other, less menu-specific crates, like Dialoguer, don’t support menu-options that only show up in search results.

See examples for some… Examples of Cartographer’s offerings

Example

(You can find more examples in the examples directory)

A basic example of a multi select menu:

// ./examples/example_menu.rs
use cartographer::{menu, menu_item, MenuOptions};

fn main() {
    let options = MenuOptions::new().cursor('➤').selected_indicator('✓');

    let menu = menu!(
        "So you should try it!: ",
        options,
        [
            menu_item!("Using Cartographer", true, 1),
            menu_item!("Making TUI menus", true, 2),
            menu_item!("Is easy", true, 3),
            menu_item!("Read on for more!", false, 0, ["Ok"])
        ]
    );

    let usr_selection = menu.serve().unwrap().unwrap();
    println!("\nYou Selected:\n{:?}", usr_selection);
}

How to Use

Adding it to your project dependencies

Simply run

cargo add cartographer

in your project directory, or add

"cartographer" = "the latest version"

to your Cargo.toml.

Creating a menu!

There are two ways you can create a menu.

The macro way, and the manual way.

The macro way is demonstrated in the example above.

An example of the manual way can be found in the examples directory. The manual way uses builder notation and the cartographer::Menu and cartographer::MenuItem structs to manually build menus and menu items.

All types handled by this crate are of type String. The values from prompts, and the return types are all strings, so I would suggest using a solution much like what can be found in the examples to easily match the return value.

But returned strings will match the supplied prompts including special formatting! So just be careful if you decide to match by strings!

Serving your menu

All menu logic is handled behind the scenes once .serve() is called on a valid Menu, and the thread will wait for the user to make their selections.

While threading with this library is probably possible (though untested), make sure that there is no terminal output sent by other threads, or visual problems will start to crop up.

Configuration

To configure how your menu looks, you can use the cartographer::MenuOptions struct and builder notation to create a configuration.

The defaults and additional options can found under the docs for MenuOptions.