- [Cartographer-rs](#org261470f)
  - [Example](#orga30eb28)
  - [How to Use](#orgb531867)
    - [Adding it to your project dependencies](#org55a0037)
    - [Creating a menu!](#org075f737)
    - [Serving your menu](#org6e78eb9)
    - [Configuration](#orgbdccb51)



<p align="center">
<img src="https://raw.githubusercontent.com/Nickiel12/cartographer/7ce0a7cac9ad708369c2e810fc77a781eec929e0/Logo.svg" width="800" alt="Cartographer Logo">
</p>


<a id="org261470f"></a>

# Cartographer-rs

Cartographer is a small library using [Console](https://crates.io/crates/console) and macros to bring &ldquo;just add water&rdquo; 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](https://docs.rs/dialoguer/latest/dialoguer/), don&rsquo;t support menu-options that only show up in search results.

[See examples for some&#x2026; Examples of Cartographer&rsquo;s offerings](https://github.com/Nickiel12/cartographer/tree/main/examples)


<a id="orga30eb28"></a>

## Example

(You can find more examples [in the examples directory](https://github.com/Nickiel12/cartographer/tree/main/examples))

A basic example of a multi select menu:

```rust

// ./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);
}

```

![gif of the above example](https://raw.githubusercontent.com/Nickiel12/cartographer/main/demo.gif)

</div>


<a id="orgb531867"></a>

## How to Use


<a id="org55a0037"></a>

### Adding it to your project dependencies

Simply run

```shell
cargo add cartographer
```

in your project directory, or add

```shell
"cartographer" = "the latest version"
```

to your `Cargo.toml`.


<a id="org075f737"></a>

### 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.](https://github.com/Nickiel12/cartographer/blob/main/examples/manual_menu.rs) 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](https://github.com/Nickiel12/cartographer/blob/main/examples/enum_matching_results.rs) 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!


<a id="org6e78eb9"></a>

### 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.


<a id="orgbdccb51"></a>

### Configuration

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

<div class="rust" id="org5a397b1">
<p>
let options = MenuOptions::new().cursor(&rsquo;➤&rsquo;).selectedindicator(&rsquo;✓&rsquo;);
</p>

</div>

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