mirror of
https://github.com/FliegendeWurst/cursive.git
synced 2024-11-09 10:50:40 +00:00
Add first tutorial
This commit is contained in:
parent
ce6992a8c5
commit
207e7e0b52
@ -59,6 +59,8 @@ Check out the other [examples](https://github.com/gyscos/Cursive/tree/master/exa
|
|||||||
|
|
||||||
_(Colors may depend on your terminal configuration.)_
|
_(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).
|
||||||
|
|
||||||
## Goals
|
## Goals
|
||||||
|
|
||||||
* **Ease of use.** Simple apps should be simple. Complex apps should be manageable.
|
* **Ease of use.** Simple apps should be simple. Complex apps should be manageable.
|
||||||
|
162
doc/tutorial_1.md
Normal file
162
doc/tutorial_1.md
Normal file
@ -0,0 +1,162 @@
|
|||||||
|
# Starting with cursive: Basics
|
||||||
|
|
||||||
|
## Target goal
|
||||||
|
|
||||||
|
In this first tutorial, we'll learn the basics of cursive,
|
||||||
|
and write a very basic first application:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
extern crate cursive;
|
||||||
|
|
||||||
|
use cursive::Cursive;
|
||||||
|
use cursive::views::TextView;
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
let mut siv = Cursive::new();
|
||||||
|
|
||||||
|
siv.add_global_callback('q', |s| s.quit());
|
||||||
|
|
||||||
|
siv.add_layer(TextView::new("Hello cursive! Press <q> to quit."));
|
||||||
|
|
||||||
|
siv.run();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Run this application, and you should have something like that:
|
||||||
|
<img src="doc/tutorial_1.png" alt="Tutorial 1 goal" />
|
||||||
|
|
||||||
|
Now that you have an idea of what we'll do, let's start from scratch.
|
||||||
|
|
||||||
|
## Project configuration
|
||||||
|
|
||||||
|
Let's create a new project
|
||||||
|
(this is basic cargo stuff I hope you're familiar with):
|
||||||
|
|
||||||
|
```text
|
||||||
|
% cargo new --bin cursive_example
|
||||||
|
```
|
||||||
|
|
||||||
|
Now, we'll add cursive to the list of dependencies in `Cargo.toml`:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[package]
|
||||||
|
name = "cursive_example"
|
||||||
|
version = "0.1.0"
|
||||||
|
|
||||||
|
[dependencies]
|
||||||
|
cursive = "*"
|
||||||
|
```
|
||||||
|
|
||||||
|
Finally, update `src/main.rs` to import it:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
extern crate cursive;
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This simple application is now ready to use cursive. So let's do just that!
|
||||||
|
|
||||||
|
## The Cursive root
|
||||||
|
|
||||||
|
The cursive library is configured through a main `Cursive` root.
|
||||||
|
A typical cursive application will consist of three phases,
|
||||||
|
all centered around this object:
|
||||||
|
|
||||||
|
1. Create a `Cursive` object.
|
||||||
|
2. Configure the `Cursive` object.
|
||||||
|
3. Run the `Cursive` object.
|
||||||
|
|
||||||
|
Of these, the configuration phase is often the largest one,
|
||||||
|
so let's skip it for now.
|
||||||
|
|
||||||
|
In its simplest form, a cursive application is therefore:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
extern crate cursive;
|
||||||
|
|
||||||
|
use cursive::Cursive;
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
let mut siv = Cursive::new();
|
||||||
|
|
||||||
|
siv.run();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
It's rather easy to identify the two steps involved.
|
||||||
|
|
||||||
|
If you run this, you'll get an empty blue terminal, with no way of properly
|
||||||
|
leaving the application (you'll have to press <Ctrl-C> to kill it).
|
||||||
|
|
||||||
|
## Interactivity
|
||||||
|
|
||||||
|
Let's first add a way to stop the application. We want to quit when the user
|
||||||
|
presses the letter `<q>`.
|
||||||
|
|
||||||
|
Cursive sends an event for every user input ; most of these are just ignored
|
||||||
|
and have no effect. The `Cursive` root has a `add_global_callback` to call
|
||||||
|
a function anytime a certain event is fired. This method takes 2 arguments:
|
||||||
|
a trigger, and a callback.
|
||||||
|
|
||||||
|
* The trigger needs to implement `Into<event::Event>`. In addition to
|
||||||
|
`event::Event` itself, this includes `event::Key`, or simply `char`. These
|
||||||
|
will trigger when the corresponding key (or letter) is pressed.
|
||||||
|
* The callback should be a function taking a `&mut Cursive` as argument. Here,
|
||||||
|
we want to quit, so we'll use `Cursive::quit` in a closure: `|s| s.quit()`.
|
||||||
|
|
||||||
|
In the end, we have:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
# src/main.rs
|
||||||
|
|
||||||
|
extern crate cursive;
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
let mut siv = Cursive::new();
|
||||||
|
|
||||||
|
siv.add_global_callback('q', |s| s.quit());
|
||||||
|
|
||||||
|
siv.run();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
As expected, running it show no visible change, but hitting the `<q>` key at
|
||||||
|
least closes the application.
|
||||||
|
|
||||||
|
## Views
|
||||||
|
|
||||||
|
`View`s are the main components of the user interface in a cursive application.
|
||||||
|
At their core, they define what to draw in a rectangle of the terminal. For
|
||||||
|
instance, a view can print a line of text, or a checkbox, etc.
|
||||||
|
|
||||||
|
Here, we'll be using a `TextView` to show a short message. `TextView` itself
|
||||||
|
can also deal with long text and do proper word-wrapping, but we won't need
|
||||||
|
that today.
|
||||||
|
|
||||||
|
The `TextView` constructor just takes the text to use: `TextView::new("...")`.
|
||||||
|
|
||||||
|
The `Cursive` root itself uses a `StackView` on the entire screen. This
|
||||||
|
`StackView` unsurprisingly stacks views in layers. It starts empty, so we'll
|
||||||
|
just need to add our `TextView` as a layer. The `Cursive::add_layer` does
|
||||||
|
exactly that.
|
||||||
|
|
||||||
|
Once we've added this line, our first application is complete:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
extern crate cursive;
|
||||||
|
|
||||||
|
use cursive::Cursive;
|
||||||
|
use cursive::views::TextView;
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
let mut siv = Cursive::new();
|
||||||
|
|
||||||
|
siv.add_global_callback('q', |s| s.quit());
|
||||||
|
|
||||||
|
siv.add_layer(TextView::new("Hello cursive! Press <q> to quit."));
|
||||||
|
|
||||||
|
siv.run();
|
||||||
|
}
|
||||||
|
```
|
BIN
doc/tutorial_1.png
Normal file
BIN
doc/tutorial_1.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 2.7 KiB |
Loading…
Reference in New Issue
Block a user