#+title: Readme

#+begin_html
<p align="center">
    <img src="./Logo.svg" style="width: 75%;" />
</p>
#+end_html

* Cartographer-rs
Cartographer is a small library using [[https://crates.io/crates/console][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 [[https://docs.rs/dialoguer/latest/dialoguer/][Dialoguer]], don't support menu-options that only show up in search results.

[[https://github.com/Nickiel12/cartographer/tree/main/examples][See examples for some... Examples of Cartographer's offerings]]

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

A basic example of a multi select menu:
#+begin_src 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);
}

#+end_src

#+begin_html
<img src="./demo.gif" style="width: 75%;" />
#+end_html

** How to Use
*** Adding it to your project dependencies
Simply run
#+begin_src shell
cargo add cartographer
#+end_src
in your project directory, or add
#+begin_src shell
"cartographer" = "the latest version"
#+end_src
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 [[https://github.com/Nickiel12/cartographer/blob/main/examples/manual_menu.rs][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 [[https://github.com/Nickiel12/cartographer/blob/main/examples/enum_matching_results.rs][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.

#+begin_rust
    let options = MenuOptions::new().cursor('➤').selected_indicator('✓');
#+end_rust

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

**** TODO add link to MenuOptions doc page when created
**** TODO fix "clear written lines" messing up when word-wrap happens. ~Term::size~ to get console width