2016-06-25 20:41:06 +00:00
# Cursive
2015-05-09 19:28:21 +00:00
2016-06-25 20:44:01 +00:00
[![Build Status ](https://travis-ci.org/gyscos/Cursive.svg?branch=master )](https://travis-ci.org/gyscos/Cursive)
2016-06-25 23:55:24 +00:00
[![crates.io ](http://meritbadge.herokuapp.com/cursive )](https://crates.io/crates/cursive)
2016-06-25 20:44:01 +00:00
[![MIT licensed ](https://img.shields.io/badge/license-MIT-blue.svg )](./LICENSE)
2015-05-09 19:28:21 +00:00
Cursive is a ncurses-based TUI (Text User Interface) library for rust. It is based on jeaye's [ncurses-rs ](https://github.com/jeaye/ncurses-rs ).
2016-06-25 20:53:04 +00:00
# [Documentation](http://gyscos.github.io/Cursive/cursive/index.html)
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
2015-05-22 23:28:23 +00:00
```
2016-06-25 23:55:24 +00:00
[dependencies]
cursive = "0.0.1"
2015-05-22 23:28:23 +00:00
```
2015-06-04 06:48:17 +00:00
(You will also need ncurses installed - if it isn't already, check in your package manager.)
2015-06-02 19:03:33 +00:00
2015-05-09 19:28:21 +00:00
```rust
extern crate cursive;
2015-05-19 20:45:41 +00:00
use cursive::Cursive;
2016-06-26 00:10:18 +00:00
use cursive::view::{TextView, Dialog};
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.
2015-05-19 18:01:16 +00:00
let mut siv = Cursive::new();
2015-05-09 19:28:21 +00:00
2016-06-26 00:10:18 +00:00
// Creates a dialog with a single "Quit" button
2015-05-25 08:15:00 +00:00
siv.add_layer(Dialog::new(TextView::new("Hello Dialog!"))
2016-06-26 00:10:18 +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
2015-05-24 21:07:30 +00:00
![Cursive dialog example ](https://raw.githubusercontent.com/Gyscos/Cursive/master/doc/cursive_example.png )
2015-05-25 08:15:00 +00:00
_(Colors may depend on your terminal configuration.)_
2015-05-24 21:07:30 +00:00
2016-06-25 20:41:06 +00:00
## Goals
2015-05-24 21:07:30 +00:00
2016-06-25 20:41:06 +00:00
* **Ease of use.** Simle apps should be simple. Complex apps should be manageable.
* **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
## _Non_-goals
2015-05-19 20:54:50 +00:00
2016-06-25 20:41:06 +00:00
* **Extreme performance.** This is a simple layout library, guys, not [compiz ](https://www.google.com/search?q=compiz&tbm=isch ) piped into [libcaca ](https://www.google.com/search?q=libcaca&tbm=isch ). Unless you are running it on your microwave's microcontroller, it's not going to be slow.
* **Multi-threaded UI.** Callback methods are blocking - careful what you're doing in there! Feel free to use threads on your side, though.
* **Complete ncurses equivalent.** You _can_ access the underlying ncurses window when creating your own custom views, so you can do what you want with that, but the main library will probably only use a subset of the ncurses features.
2015-05-19 17:01:54 +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.
Also, Cursive currently expects every codepoint to be a one-column character, so some things may break with exotic characters...
### Input
2015-06-06 22:05:01 +00:00
* 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.
2016-06-25 23:36:22 +00:00
Here is the support table for input keys. Tested terminals are mostly Gnome terminal and Linux TTY, xterm, and a few others now and then.
2015-06-06 22:05:01 +00:00
| | Key | Shift+Key | Ctrl+Key | Shift+Ctrl+Key |
|--------------------------|:----:|:----------------------:|:--------------------------:|:---------------:|
| Letters | All | All | All (except c,z,q,s,i,h,m) | None |
| Numbers | All | All | None (can crash the app) | None |
| Punctuation | All | All | None (can crash the app) | None |
| Enter, Esc | All | None | None | None |
| Left, Right arrow keys | All | VTE+Xterm | VTE+Xterm | VTE+Xterm |
| Up, Down arrow keys | All | Xterm | VTE+Xterm | Xterm |
| Ins | All | None (paste clipboard) | Xterm | None |
| Del | All | VTE+Xterm | VTE+Xterm | VTE+Xterm |
| Home, End | All | Xterm | Xterm | Xterm |
2016-06-25 23:36:22 +00:00
| PageUp, PageDown | All | All | All | None |
| Fn keys: F1-F4 | All | All except Konsole | Gnome+XTerm | Gnome+Xterm |
| Fn keys: F5-F8 | All | All | All except TTY | All except TTY |
| Fn keys: F9-F12 | All | All except TTY | All except TTY | All except TTY |
2015-06-06 22:05:01 +00:00
| PrtScn, ScrollLock | None | None | None | None |
| Window, Menu | None | None | None | None |
2015-06-06 20:51:21 +00:00
2016-06-25 20:41:06 +00:00
## Contribute
2015-05-31 20:11:50 +00:00
You want to help? Great! Here is a non-exhaustive list of things you could do:
* Provide example use-case: a good idea of application for existing or new components.
2016-06-25 23:36:22 +00:00
* Check compatibility: run the `key_codes` example on your favorite terminal, and report the results!
2015-05-31 20:11:50 +00:00
* Test and reports issues: a bug won't get fixed if we don't know it's there.
* Hack the code! If you feel confident with rust, pick an issue you like and hack away!