diff --git a/Readme.md b/Readme.md index 087bb1c..8c87cc0 100644 --- a/Readme.md +++ b/Readme.md @@ -59,7 +59,12 @@ Check out the other [examples](https://github.com/gyscos/Cursive/tree/master/exa _(Colors may depend on your terminal configuration.)_ -You may also have a look at the [tutorial](https://github.com/gyscos/Cursive/tree/master/doc/tutorial_1.md). +## Tutorials + +These tutorials may help you get started with cursive: + +* [Starting with cursive: Basics](https://github.com/gyscos/Cursive/tree/master/doc/tutorial_1.md) +* [Starting with cursive: Intermediate](https://github.com/gyscos/Cursive/tree/master/doc/tutorial_2.md) ## Goals diff --git a/doc/tutorial_1.md b/doc/tutorial_1.md index ec808fa..e967234 100644 --- a/doc/tutorial_1.md +++ b/doc/tutorial_1.md @@ -3,7 +3,7 @@ ## Target goal In this first tutorial, we'll learn the basics of cursive, -and write a very basic first application: +and write a very basic first application: ```rust extern crate cursive; diff --git a/doc/tutorial_2.md b/doc/tutorial_2.md new file mode 100644 index 0000000..6f20468 --- /dev/null +++ b/doc/tutorial_2.md @@ -0,0 +1,215 @@ +# Starting with cursive: Intermediate + +## Target goal + +This time, we'll work on a slightly bigger example, where the user will need to +actually make some choices. Here is what the code will look like: + +```rust +extern crate cursive; + +use cursive::Cursive; +use cursive::views::Dialog; + +fn main() { + let mut siv = Cursive::new(); + + siv.add_layer(Dialog::text("This is a survey!\nPress when you're ready.") + .title("Important survey") + .button("Next", show_next)); + + siv.run(); +} + +fn show_next(s: &mut Cursive) { + s.pop_layer(); + s.add_layer(Dialog::text("Did you do the thing?") + .title("Question 1") + .button("Yes!", |s| show_answer(s, "I knew it! Well done!")) + .button("No!", |s| show_answer(s, "I knew you couldn't be trusted!")) + .button("Uh?", |s| s.add_layer(Dialog::info("Try again!")))); +} + +fn show_answer(s: &mut Cursive, msg: &str) { + s.pop_layer(); + s.add_layer(Dialog::text(msg) + .title("Results") + .button("Finish", |s| s.quit())); +} +``` + +Tutorial 2 goal + +## Preparation + +This time you're not a beginner anymore, so we'll skip the introduction! +Let's start from a basic cursive application: + +```rust +extern crate cursive + +use cursive::Cursive; + +fn main() { + let mut siv = Cursive::new(); + + siv.run(); +} +``` + +## Dialogs + +Instead of directly using a [`TextView`], we'll use a [`Dialog`] this time. +A dialog is wrapper with a frame around another view, and optionally a title +and/or buttons. + +[`Dialog::new`] directly takes a view, so we'll directly give it the +`TextView`: + +```rust +extern crate cursive; + +use cursive::Cursive; +use cursive::views::Dialog; +use cursive::views::TextView; + +fn main() { + let mut siv = Cursive::new(); + + siv.add_layer(Dialog::new(TextView::new("..."))); + + siv.run(); +} +``` + +Since creating a `Dialog` around a `TextView` is a pretty common task, +[Dialog::text`] is a shortcut function that directly does that. Our line +becomes a little shorter (and we don't need to import +`cursive::views::TextView` anymore): + +```rust +siv.add_layer(Dialog::text("...")); +``` + +Next, let's add a title. To do that, `Dialog` has a chainable [`Dialog::title`] +method. It takes the dialog by value, and return it back, making function +chains easy: + +```rust +siv.add_layer(Dialog::text("...").title("...")); +``` + +This way of chaining method to set-up the view is very common in cursive. Most +views provide chainable variants of their methods, to allow creating the view +and configuring it in one spot. + +[`Dialog::title`]: http://gyscos.github.io/Cursive/cursive/views/struct.Dialog.html#method.title + +## Buttons + +Our dialog looks better than a `TextView` alone, but it's still missing some +action. Adding some buttons there will help. + +Just like with the title, `Dialog` has a [`Dialog::button`] method to add a +button in a chain. This method takes a label and a callback, the same kind +we saw in the previous tutorial: + +```rust +siv.add_layer(Dialog::text("...") + .title("...") + .button("Quit", |s| s.quit())); +``` + +Only this time, we don't want to exit the application right away. Instead of +packing everything into the closure, let's use a separate function for the +callback. Here is the current state: + +```rust +extern crate cursive; + +use cursive::Cursive; +use cursive::views::Dialog; + +fn main() { + let mut siv = Cursive::new(); + + siv.add_layer(Dialog::text("This is a survey!\nPress when you're ready.") + .title("Important survey") + .button("Next", show_next)); + + siv.run(); +} + +fn show_next(s: &mut Cursive) { + // Empty for now +} +``` + +## Layers + +After the user presses the `` button, we want to hide the current popup +and show a new one instead. We'll use [`Cursive::pop_layer`] to do that. + +Then, we add a new `Dialog`, this time with a few more buttons: + +```rust +fn show_next(s: &mut Cursive) { + s.pop_layer(); + s.add_layer(Dialog::text("Did you do the thing?") + .title("Question 1") + .button("Yes!", |s| ()) //< Do something interesting here... + .button("No!", |s| ()) //< And here as well... + .button("Uh?", |s| ()); //< And finally here too. +} +``` + +As you see, `Dialog::button()` can be called several times to add more buttons. + +The `` button will add a new popup, without removing the current one: +it'll act as a dismissable infobox. `Dialog::info()` is a shortcut to build +such a popup: + +```rust +fn show_next(s: &mut Cursive) { + s.pop_layer(); + s.add_layer(Dialog::text("Did you do the thing?") + .title("Question 1") + .button("Yes!", |s| ()) //< We'll fill this callback soon, + .button("No!", |s| ()) //< along with this one. + .button("Uh?", |s| s.add_layer(Dialog::info("Try again!")))); +} +``` + +Finally, let's have the "Yes" and "No" buttons use the same callback method to +print a message, but with a different text parameter: + +```rust +fn show_next(s: &mut Cursive) { + s.pop_layer(); + s.add_layer(Dialog::text("Did you do the thing?") + .title("Question 1") + .button("Yes!", |s| show_answer(s, "I knew it! Well done!")) + .button("No!", |s| show_answer(s, "I knew you couldn't be trusted!")) + .button("Uh?", |s| s.add_layer(Dialog::info("Try again!")))); +} + +fn show_answer(s: &mut Cursive, msg: &str) { + s.pop_layer(); + s.add_layer(Dialog::text(msg) + .title("Results") + .button("Finish", |s| s.quit())); +} +``` + +Here, `show_answer()` does the same thing: remove the previous layer, and add +a new `Dialog` instead. + +[`Cursive::pop_layer`]: http://gyscos.github.io/Cursive/cursive/struct.Cursive.html#method.pop_layer + +## Conclusion + +Your code should now look like the one at the top of this guide. + +As you've seen, the `Dialog` view is a nice way to present a `TextView`, but it +works with any other content. Actually, most layers you'll add will start with +a `Dialog` wrapping some other view. diff --git a/doc/tutorial_2.png b/doc/tutorial_2.png new file mode 100644 index 0000000..2936b33 Binary files /dev/null and b/doc/tutorial_2.png differ