cursive/Readme.md

112 lines
5.3 KiB
Markdown
Raw Normal View History

2016-06-25 20:41:06 +00:00
# Cursive
2015-05-09 19:28:21 +00:00
2016-10-02 22:59:31 +00:00
[![crates.io](https://meritbadge.herokuapp.com/cursive)](https://crates.io/crates/cursive)
2019-06-19 18:39:11 +00:00
[![Build Status (travis)](https://travis-ci.org/gyscos/cursive.svg?branch=master)](https://travis-ci.org/gyscos/cursive)
2018-06-19 06:04:24 +00:00
[![Build status (appveyor)](https://ci.appveyor.com/api/projects/status/uk5pww718jsp5x2l/branch/master?svg=true)](https://ci.appveyor.com/project/gyscos/cursive/branch/master)
2016-06-25 20:44:01 +00:00
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
2017-02-27 22:22:43 +00:00
[![Gitter chat](https://badges.gitter.im/gyscos/cursive.png)](https://gitter.im/cursive-rs/cursive)
2016-06-25 20:44:01 +00:00
2018-06-19 06:04:24 +00:00
2019-06-19 18:39:11 +00:00
Cursive is a TUI (Text User Interface) library for rust. It uses ncurses by default, but [other backends are available](https://github.com/gyscos/cursive/wiki/Backends).
2016-08-03 17:47:13 +00:00
It allows you to build rich user interfaces for terminal applications.
2015-05-09 19:28:21 +00:00
2017-11-17 19:46:29 +00:00
# [Documentation](http://docs.rs/cursive)
2016-06-25 20:53:04 +00:00
2015-05-19 17:01:54 +00:00
It is designed to be safe and easy to use:
2015-05-09 19:28:21 +00:00
2016-10-07 17:17:28 +00:00
```toml
2016-06-25 23:55:24 +00:00
[dependencies]
2019-05-09 16:39:56 +00:00
cursive = "0.12"
2015-05-22 23:28:23 +00:00
```
Or to use the latest git version:
2016-10-07 17:17:28 +00:00
```toml
[dependencies]
2019-06-19 18:39:11 +00:00
cursive = { git = "https://github.com/gyscos/cursive" }
```
2019-06-19 18:39:11 +00:00
([You will also need ncurses installed.](https://github.com/gyscos/cursive/wiki/Install-ncurses))
2016-09-28 22:22:21 +00:00
```rust,no_run
use cursive::Cursive;
use cursive::views::{Dialog, TextView};
2015-05-09 19:28:21 +00:00
fn main() {
2016-06-26 00:10:18 +00:00
// Creates the cursive root - required for every application.
2018-08-01 19:54:51 +00:00
let mut siv = Cursive::default();
2015-05-09 19:28:21 +00:00
2016-06-26 00:10:18 +00:00
// Creates a dialog with a single "Quit" button
siv.add_layer(Dialog::around(TextView::new("Hello Dialog!"))
2016-06-29 13:06:28 +00:00
.title("Cursive")
.button("Quit", |s| s.quit()));
2015-05-09 19:28:21 +00:00
2015-05-19 18:01:16 +00:00
// Starts the event loop.
siv.run();
2015-05-09 19:28:21 +00:00
}
```
2015-05-19 17:01:54 +00:00
2019-06-19 18:39:11 +00:00
[![Cursive dialog example](https://raw.githubusercontent.com/gyscos/cursive/master/doc/cursive_example.png)](examples/dialog.rs)
2015-05-24 21:07:30 +00:00
2019-06-19 18:39:11 +00:00
Check out the other [examples](https://github.com/gyscos/cursive/tree/master/examples) to get these results, and more:
2016-07-18 01:18:20 +00:00
<div>
2018-03-14 23:02:02 +00:00
<a href="examples/edit.rs"><img src="https://imgur.com/CQgSwly.png" alt="edit.rs example", width="48%" /></a>
<a href="examples/lorem.rs"><img src="https://imgur.com/hW9M9MV.png" alt="lorem.rs example", width="48%" /></a>
<a href="examples/menubar.rs"><img src="https://imgur.com/xx3lZPz.png" alt="menubar.rs example", width="48%" /></a>
<a href="examples/select.rs"><img src="https://imgur.com/couty0n.png" alt="select.rs example", width="48%" /></a>
<a href="examples/mines/"><img src="https://imgur.com/vNteYyy.png" alt="mines example", width="48%" /></a>
<a href="examples/theme.rs"><img src="https://i.imgur.com/3Yleozc.png" alt="theme.rs example", width="48%" /></a>
</div>
2016-07-18 01:18:20 +00:00
_(Colors may depend on your terminal configuration.)_
2015-05-24 21:07:30 +00:00
2016-08-20 08:22:07 +00:00
## Tutorials
These tutorials may help you get started with cursive:
2019-06-19 18:39:11 +00:00
* [Starting with cursive: (1/3)](https://github.com/gyscos/cursive/tree/master/doc/tutorial_1.md)
* [Starting with cursive: (2/3)](https://github.com/gyscos/cursive/tree/master/doc/tutorial_2.md)
* [Starting with cursive: (3/3)](https://github.com/gyscos/cursive/tree/master/doc/tutorial_3.md)
2016-08-16 00:26:44 +00:00
2017-04-18 17:30:55 +00:00
## Third-party views
Here are a few crates implementing new views for you to use:
* [cursive_table_view](https://github.com/BonsaiDen/cursive_table_view)
* [cursive_calendar_view](https://github.com/BonsaiDen/cursive_calendar_view)
2017-06-06 18:16:17 +00:00
* [cursive_tree_view](https://github.com/BonsaiDen/cursive_tree_view)
2017-12-21 10:34:08 +00:00
* [cursive_hexview](https://github.com/hellow554/cursive_hexview)
2017-04-18 17:30:55 +00:00
2016-06-25 20:41:06 +00:00
## Goals
2015-05-24 21:07:30 +00:00
2016-06-26 00:19:26 +00:00
* **Ease of use.** Simple apps should be simple. Complex apps should be manageable.
2016-06-25 20:41:06 +00:00
* **Linux TTY Compatibility.** Colors may suffer, and UTF-8 may be too much, but most features *must* work properly on a Linux TTY.
* **Flexibility.** This library should be able to handle simple UI scripts, complex real-time applications, or even games.
* In particular, it tries to have enough features to recreate these kind of tools:
* [menuconfig](http://en.wikipedia.org/wiki/Menuconfig#/media/File:Linux_x86_3.10.0-rc2_Kernel_Configuration.png)
* [nmtui](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/sec-Configure_a_Network_Team_Using_the_Text_User_Interface_nmtui.html)
2015-05-19 20:54:50 +00:00
2016-06-25 20:41:06 +00:00
## Compatibility
2015-06-06 20:51:21 +00:00
First off, terminals are messy. A small set of features is standard, but beyond that, almost every terminal has its own implementation.
### Output
* **Colors**: the basic 8-colors palette should be broadly supported. User-defined colors is not supported in the raw linux TTY, but should work in most terminals, although it's still kinda experimental.
* **UTF-8**: Currently Cursive really expects a UTF-8 locale. It may eventually get patched to support window borders on other locales, but it's not a priority.
2019-06-19 18:39:11 +00:00
There is initial support for [wide characters](https://en.wikipedia.org/wiki/CJK_characters). [RTL](https://en.wikipedia.org/wiki/Right-to-left) support [is planned](https://github.com/gyscos/cursive/issues/31), but still very early.
2015-06-06 20:51:21 +00:00
### Input
* The `key_codes` example can be a useful tool to see how the library reacts to various key presses.
* Keep in mind that if the terminal has shortcuts registered, they probably won't be transmitted to the app.
* UTF-8 input should work fine in a unicode-enabled terminal emulator, but raw linux TTY may be more capricious.
## [Contributing](CONTRIBUTING.md)
2019-03-04 19:12:51 +00:00
## Alternatives
2019-06-19 18:39:11 +00:00
See also [tui-rs](https://github.com/fdehau/tui-rs) - and a small [comparison page](https://github.com/gyscos/cursive/wiki/Cursive-vs-tui%E2%80%90rs).