docs(example): add break word behaviour to paragraph example

Without a terminal-resetting panic hook there are two main problems when
an application panics:

1.  The report of the panic is distorted because the terminal has not
    properly left the alternate screen and is still in raw mode.

2.  The terminal needs to be manually reset with the `reset` command.

To avoid this, the standard panic hook can be extended to first reset
the terminal.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,30 +1,60 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Create an issue about a bug you encountered
 title: ''
 labels: bug
 assignees: ''
-
 ---
 
-**Describe the bug**
+<!--
+Hi there, sorry `tui` is not working as expected.
+Please fill this bug report conscientiously.
+A detailed and complete issue is more likely to be processed quickly.
+-->
+
+## Description
+<!--
 A clear and concise description of what the bug is.
+-->
 
-**To Reproduce**
-If possible include a code sample exhibiting the problem.
 
-**Expected behavior**
+## To Reproduce
+<!--
+Try to reduce the issue to a simple code sample exhibiting the problem.
+Ideally, fork the project and add a test or an example.
+-->
+
+
+## Expected behavior
+<!--
 A clear and concise description of what you expected to happen.
+-->
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. Linux,Windows]
- - Terminal Emulator [e.g xterm, Konsole, Terminal, iTerm2, ConEmu]
- - Font [e.g Inconsolata, Monospace]
- - Crate version [e.g. 0.7]
- - Backend [e.g termion, crossterm]
+## Screenshots
+<!--
+If applicable, add screenshots, gifs or videos to help explain your problem.
+-->
 
-**Additional context**
+
+## Environment
+<!--
+Add a description of the systems where you are observing the issue. For example:
+- OS: Linux
+- Terminal Emulator: xterm
+- Font: Inconsolata (Patched)
+- Crate version: 0.7
+- Backend: termion
+-->
+
+- OS:
+- Terminal Emulator:
+- Font:
+- Crate version:
+- Backend:
+
+## Additional context
+<!--
 Add any other context about the problem here.
+If you already looked into the issue, include all the leads you have explored.
+-->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,14 +7,26 @@ assignees: ''
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
+## Problem
+<!--
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+-->
 
-**Describe the solution you'd like**
+## Solution
+<!--
 A clear and concise description of what you want to happen.
+Things to consider:
+- backward compatibility
+- ease of use of the API (https://rust-lang.github.io/api-guidelines/)
+- consistency with the rest of the crate
+-->
 
-**Describe alternatives you've considered**
+## Alternatives
+<!--
 A clear and concise description of any alternative solutions or features you've considered.
+-->
 
-**Additional context**
+## Additional context
+<!--
 Add any other context or screenshots about the feature request here.
+-->

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Description
+<!--
+A clear and concise description of what this PR changes.
+-->
+
+## Testing guidelines
+<!--
+A clear and concise description of how the changes can be tested.
+For example, you can include a command to run the relevant tests or examples.
+You can also include screenshots of the expected behavior.
+-->
+
+## Checklist
+
+* [ ] I have read the [contributing guidelines](../CONTRIBUTING.md).
+* [ ] I have added relevant tests.
+* [ ] I have documented all new additions.

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 name: CI
 
 env:
-  CI_CARGO_MAKE_VERSION: 0.32.9
+  CI_CARGO_MAKE_VERSION: 0.35.8
 
 jobs:
   linux:
@@ -17,10 +17,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        rust: ["1.46.0", "stable"]
+        rust: ["1.56.1", "stable"]
     steps:
-      - name: "Install dependencies"
-        run: sudo apt-get install libncurses5-dev
       - uses: hecrj/setup-rust-action@967aec96c6a27a0ce15c1dac3aaba332d60565e2
         with:
           rust-version: ${{ matrix.rust }}
@@ -38,22 +36,16 @@ jobs:
       - name: "Install cargo-make"
         if: steps.cache-cargo-make.outputs.cache-hit != 'true'
         run: cargo install cargo-make --version ${{ env.CI_CARGO_MAKE_VERSION }}
-      - name: "Format"
-        run: cargo make fmt
-      - name: "Check"
-        run: cargo make check
-      - name: "Test"
-        run: cargo make test
+      - name: "Format / Build / Test"
+        run: cargo make ci
         env:
           RUST_BACKTRACE: full
-      - name: "Clippy"
-        run: cargo make clippy
   windows:
     name: Windows
     runs-on: windows-latest
     strategy:
       matrix:
-        rust: ["1.46.0", "stable"]
+        rust: ["1.56.1", "stable"]
     steps:
       - uses: actions/checkout@v1
       - uses: hecrj/setup-rust-action@967aec96c6a27a0ce15c1dac3aaba332d60565e2
@@ -73,13 +65,7 @@ jobs:
       - name: "Install cargo-make"
         if: steps.cache-cargo-make.outputs.cache-hit != 'true'
         run: cargo install cargo-make --version ${{ env.CI_CARGO_MAKE_VERSION }}
-      - name: "Format"
-        run: cargo make fmt
-      - name: "Check"
-        run: cargo make check
-      - name: "Test"
-        run: cargo make test
+      - name: "Format / Build / Test"
+        run: cargo make ci
         env:
           RUST_BACKTRACE: full
-      - name: "Clippy"
-        run: cargo make clippy

CHANGELOG.md

@@ -2,6 +2,81 @@
 
 ## To be released
 
+## v0.18.0 - 2022-04-24
+
+### Features
+
+* Update `crossterm` to `0.23`
+
+## v0.17.0 - 2022-01-22
+
+### Features
+
+* Add option to `widgets::List` to repeat the hightlight symbol for each line of multi-line items (#533).
+* Add option to control the alignment of `Axis` labels in the `Chart` widget (#568).
+
+### Breaking changes
+
+* The minimum supported rust version is now `1.56.1`.
+
+#### New default backend and consolidated backend options (#553)
+
+* `crossterm` is now the default backend.
+If you are already using the `crossterm` backend, you can simplify your dependency specification in `Cargo.toml`:
+```diff
+- tui = { version = "0.16", default-features = false, features = ["crossterm"] }
++ tui = "0.17"
+```
+If you are using the `termion` backend, your `Cargo` is now a bit more verbose:
+```diff
+- tui = "0.16"
++ tui = { version = "0.17", default-features = false, features = ["termion"] }
+```
+
+`crossterm` has also been bumped to version `0.22`.
+
+Because of their apparent low usage, `curses` and `rustbox` backends have been removed.
+If you are using one of them, you can import their last implementation in your own project:
+* [curses](https://github.com/fdehau/tui-rs/blob/v0.16.0/src/backend/curses.rs)
+* [rustbox](https://github.com/fdehau/tui-rs/blob/v0.16.0/src/backend/rustbox.rs)
+
+#### Canvas labels (#543)
+
+* Labels of the `Canvas` widget are now `text::Spans`.
+The signature of `widgets::canvas::Context::print` has thus been updated:
+```diff
+- ctx.print(x, y, "Some text", Color::Yellow);
++ ctx.print(x, y, Span::styled("Some text", Style::default().fg(Color::Yellow)))
+```
+
+## v0.16.0 - 2021-08-01
+
+### Features
+
+* Update `crossterm` to `0.20`.
+* Add `From<Cow<str>>` implementation for `text::Text` (#471).
+* Add option to right or center align the title of a `widgets::Block` (#462).
+
+### Fixes
+
+* Apply label style in `widgets::Gauge` and avoid panics because of overflows with long labels (#494).
+* Avoid panics because of overflows with long axis labels in `widgets::Chart` (#512).
+* Fix computation of column widths in `widgets::Table` (#514).
+* Fix panics because of invalid offset when input changes between two frames in `widgets::List` and
+  `widgets::Chart` (#516).
+
+## v0.15.0 - 2021-05-02
+
+### Features
+
+* Update `crossterm` to `0.19`.
+* Update `rand` to `0.8`.
+* Add a read-only view of the terminal state after the draw call (#440).
+
+### Fixes
+
+* Remove compile warning in `TestBackend::assert_buffer` (#466).
+
 ## v0.14.0 - 2021-01-01
 
 ### Breaking changes

CONTRIBUTING.md

@@ -1,12 +1,21 @@
 # Contributing
 
+## Building
+
 [cargo-make]: https://github.com/sagiegurari/cargo-make "cargo-make"
 
-`tui` is an ordinary Rust project where common tasks are managed with [cargo-make]. It wraps common
-`cargo` commands with sane defaults depending on your platform of choice. Bulding the project should
-be as easy as running `cargo make`.
+`tui` is an ordinary Rust project where common tasks are managed with [cargo-make].
+It wraps common `cargo` commands with sane defaults depending on your platform of choice.
+Building the project should be as easy as running `cargo make build`.
 
-## Continous Integration
+## :hammer_and_wrench: Pull requests
+
+All contributions are obviously welcome.
+Please include as many details as possible in your PR description to help the reviewer (follow the provided template).
+Make sure to highlight changes which may need additional attention or you are uncertain about.
+Any idea with a large scale impact on the crate or its users should ideally be discussed in a "Feature Request" issue beforehand.
+
+## Continuous Integration
 
 We use Github Actions for the CI where we perform the following checks:
 - The code should compile on `stable` and the Minimum Supported Rust Version (MSRV).
@@ -14,13 +23,11 @@ We use Github Actions for the CI where we perform the following checks:
 - The code should conform to the default format enforced by `rustfmt`.
 - The code should not contain common style issues `clippy`.
 
-You can also check most of those things yourself locally using `cargo make ci` which will offer you
-a shorter feedback loop.
+You can also check most of those things yourself locally using `cargo make ci` which will offer you a shorter feedback loop.
 
 ## Tests
 
-The test coverage of the crate is far from being ideal but we already have a fair amount of tests in
-place. Beside the usal doc and unit tests, one of the most valuable test you can write for `tui` is
-a test again the `TestBackend` which allows you to assert the content of the output buffer that
-would have been flushed to the termminal after a given draw call (see `widgets_block_renders` in
-[tests/widgets_block.rs](./tests/widget_block.rs) for an example).
+The test coverage of the crate is far from being ideal but we already have a fair amount of tests in place.
+Beside the usual doc and unit tests, one of the most valuable test you can write for `tui` is a test again the `TestBackend`.
+It allows you to assert the content of the output buffer that would have been flushed to the terminal after a given draw call.
+See `widgets_block_renders` in [tests/widgets_block.rs](./tests/widget_block.rs) for an example.

Cargo.toml

@@ -1,127 +1,93 @@
 [package]
 name = "tui"
-version = "0.14.0"
+version = "0.18.0"
 authors = ["Florian Dehau <work@fdehau.com>"]
 description = """
 A library to build rich terminal user interfaces or dashboards
 """
-documentation = "https://docs.rs/tui/0.14.0/tui/"
+documentation = "https://docs.rs/tui/0.18.0/tui/"
 keywords = ["tui", "terminal", "dashboard"]
 repository = "https://github.com/fdehau/tui-rs"
 readme = "README.md"
 license = "MIT"
 exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
 autoexamples = true
-edition = "2018"
+edition = "2021"
 
 [badges]
 
 [features]
-default = ["termion"]
-curses = ["easycurses", "pancurses"]
+default = ["crossterm"]
 
 [dependencies]
-bitflags = "1.0"
+bitflags = "1.3"
 cassowary = "0.3"
 unicode-segmentation = "1.2"
 unicode-width = "0.1"
 termion = { version = "1.5", optional = true }
-rustbox = { version = "0.11", optional = true }
-crossterm = { version = "0.19", optional = true }
-easycurses = { version = "0.12.2", optional = true }
-pancurses = { version = "0.16.1", optional = true, features = ["win32a"] }
-serde = { version = "1", "optional" = true, features = ["derive"]}
+crossterm = { version = "0.23", optional = true }
+serde = { version = "1", optional = true, features = ["derive"]}
 
 [dev-dependencies]
-rand = "0.7"
+rand = "0.8"
 argh = "0.1"
 
-[[example]]
-name = "canvas"
-path = "examples/canvas.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "user_input"
-path = "examples/user_input.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "gauge"
-path = "examples/gauge.rs"
-required-features = ["termion"]
-
 [[example]]
 name = "barchart"
-path = "examples/barchart.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "chart"
-path = "examples/chart.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "paragraph"
-path = "examples/paragraph.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "list"
-path = "examples/list.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "table"
-path = "examples/table.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "tabs"
-path = "examples/tabs.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "custom_widget"
-path = "examples/custom_widget.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "layout"
-path = "examples/layout.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "popup"
-path = "examples/popup.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "block"
-path = "examples/block.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "sparkline"
-path = "examples/sparkline.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "termion_demo"
-path = "examples/termion_demo.rs"
-required-features = ["termion"]
-
-[[example]]
-name = "rustbox_demo"
-path = "examples/rustbox_demo.rs"
-required-features = ["rustbox"]
-
-[[example]]
-name = "crossterm_demo"
-path = "examples/crossterm_demo.rs"
 required-features = ["crossterm"]
 
 [[example]]
-name = "curses_demo"
-path = "examples/curses_demo.rs"
-required-features = ["curses"]
+name = "block"
+required-features = ["crossterm"]
+
+[[example]]
+name = "canvas"
+required-features = ["crossterm"]
+
+[[example]]
+name = "chart"
+required-features = ["crossterm"]
+
+[[example]]
+name = "custom_widget"
+required-features = ["crossterm"]
+
+[[example]]
+name = "gauge"
+required-features = ["crossterm"]
+
+[[example]]
+name = "layout"
+required-features = ["crossterm"]
+
+[[example]]
+name = "list"
+required-features = ["crossterm"]
+
+[[example]]
+name = "panic"
+required-features = ["crossterm"]
+
+[[example]]
+name = "paragraph"
+required-features = ["crossterm"]
+
+[[example]]
+name = "popup"
+required-features = ["crossterm"]
+
+[[example]]
+name = "sparkline"
+required-features = ["crossterm"]
+
+[[example]]
+name = "table"
+required-features = ["crossterm"]
+
+[[example]]
+name = "tabs"
+required-features = ["crossterm"]
+
+[[example]]
+name = "user_input"
+required-features = ["crossterm"]

Makefile.toml

@@ -1,28 +1,34 @@
 [config]
 skip_core_tasks = true
 
-[env.TUI_FEATURES]
-source = "${CARGO_MAKE_RUST_TARGET_OS}"
-default_value = "unknown"
-
-[env.TUI_FEATURES.mapping]
-linux = "serde,crossterm,termion,rustbox,curses"
-macos = "serde,crossterm,termion,rustbox,curses"
-windows = "serde,crossterm"
-
-[tasks.default]
-dependencies = [
-  "check",
-]
-
 [tasks.ci]
-dependencies = [
-  "fmt",
-  "check",
-  "test",
-  "clippy",
+run_task = [
+    { name = "ci-unix", condition = { platforms = ["linux", "mac"] } },
+    { name = "ci-windows", condition = { platforms = ["windows"] } },
 ]
 
+[tasks.ci-unix]
+private = true
+dependencies = [
+    "fmt",
+    "check-crossterm",
+    "check-termion",
+    "test-crossterm",
+    "test-termion",
+    "clippy-crossterm",
+    "clippy-termion",
+    "test-doc",
+]
+
+[tasks.ci-windows]
+private = true
+dependencies = [
+    "fmt",
+    "check-crossterm",
+    "test-crossterm",
+    "clippy-crossterm",
+    "test-doc",
+]
 
 [tasks.fmt]
 command = "cargo"
@@ -33,8 +39,17 @@ args = [
   "--check",
 ]
 
+[tasks.check-crossterm]
+env = { TUI_FEATURES = "serde,crossterm" }
+run_task = "check"
+
+[tasks.check-termion]
+env = { TUI_FEATURES = "serde,termion" }
+run_task = "check"
+
 [tasks.check]
 command = "cargo"
+condition = { env_set = ["TUI_FEATURES"] }
 args = [
   "check",
   "--no-default-features",
@@ -43,8 +58,17 @@ args = [
   "--all-targets",
 ]
 
+[tasks.build-crossterm]
+env = { TUI_FEATURES = "serde,crossterm" }
+run_task = "build"
+
+[tasks.build-termion]
+env = { TUI_FEATURES = "serde,termion" }
+run_task = "build"
+
 [tasks.build]
 command = "cargo"
+condition = { env_set = ["TUI_FEATURES"] }
 args = [
   "build",
   "--no-default-features",
@@ -53,10 +77,20 @@ args = [
   "--all-targets",
 ]
 
+[tasks.clippy-crossterm]
+env = { TUI_FEATURES = "serde,crossterm" }
+run_task = "clippy"
+
+[tasks.clippy-termion]
+env = { TUI_FEATURES = "serde,termion" }
+run_task = "clippy"
+
 [tasks.clippy]
 command = "cargo"
+condition = { env_set = ["TUI_FEATURES"] }
 args = [
   "clippy",
+  "--all-targets",
   "--no-default-features",
   "--features",
   "${TUI_FEATURES}",
@@ -65,23 +99,17 @@ args = [
   "warnings",
 ]
 
+[tasks.test-crossterm]
+env = { TUI_FEATURES = "serde,crossterm" }
+run_task = "test"
+
+[tasks.test-termion]
+env = { TUI_FEATURES = "serde,termion" }
+run_task = "test"
+
 [tasks.test]
-linux_alias = "test-unix"
-mac_alias = "test-unix"
-windows_alias = "test-windows"
-
-[tasks.test-unix]
-command = "cargo"
-args = [
-  "test",
-  "--no-default-features",
-  "--features",
-  "${TUI_FEATURES}"
-]
-
-# Documentation tests cannot be run on Windows for now
-[tasks.test-windows]
 command = "cargo"
+condition = { env_set = ["TUI_FEATURES"] }
 args = [
   "test",
   "--no-default-features",
@@ -92,39 +120,29 @@ args = [
   "--examples",
 ]
 
+[tasks.test-doc]
+command = "cargo"
+args = [
+  "test",
+  "--doc",
+]
+
 [tasks.run-example]
 private = true
-condition = { env_set = ["TUI_EXAMPLE_NAME", "TUI_FEATURES"] }
+condition = { env_set = ["TUI_EXAMPLE_NAME"] }
 command = "cargo"
 args = [
     "run",
-    "--features",
-    "${TUI_FEATURES}",
     "--release",
     "--example",
     "${TUI_EXAMPLE_NAME}"
 ]
 
-[tasks.run-example-windows]
-private = true
-condition = { env = {"TUI_EXAMPLE_NAME" = "crossterm_demo"} }
-run_task = "run-example"
-
-[tasks.run-example-router]
-private = true
-run_task = [
-    { name = "run-example-windows", condition = { platforms = ["window"] } },
-    { name = "run-example" }
-]
-
 [tasks.build-examples]
-condition = { env_set = ["TUI_FEATURES"] }
 command = "cargo"
 args = [
     "build",
     "--examples",
-    "--features",
-    "${TUI_FEATURES}",
     "--release"
 ]
 
@@ -137,6 +155,6 @@ for file in ${files}
   name = basename ${file}
   name = substring ${name} -3
   set_env TUI_EXAMPLE_NAME ${name}
-  cm_run_task run-example-router
+  cm_run_task run-example
 end
 '''

README.md

@@ -11,15 +11,9 @@ user interfaces and dashboards. It is heavily inspired by the `Javascript`
 library [blessed-contrib](https://github.com/yaronn/blessed-contrib) and the
 `Go` library [termui](https://github.com/gizak/termui).
 
-The library itself supports four different backends to draw to the terminal. You
-can either choose from:
-
+The library supports multiple backends:
+  - [crossterm](https://github.com/crossterm-rs/crossterm) [default]
   - [termion](https://github.com/ticki/termion)
-  - [rustbox](https://github.com/gchp/rustbox)
-  - [crossterm](https://github.com/crossterm-rs/crossterm)
-  - [pancurses](https://github.com/ihalila/pancurses)
-
-However, some features may only be available in one of the four.
 
 The library is based on the principle of immediate rendering with intermediate
 buffers. This means that at each new frame you should build all widgets that are
@@ -34,58 +28,53 @@ you may rely on the previously cited libraries to achieve such features.
 
 ### Rust version requirements
 
-Since version 0.10.0, `tui` requires **rustc version 1.44.0 or greater**.
+Since version 0.17.0, `tui` requires **rustc version 1.56.1 or greater**.
 
 ### [Documentation](https://docs.rs/tui)
 
 ### Demo
 
-The demo shown in the gif can be run with all available backends
-(`examples/*_demo.rs` files). For example to see the `termion` version one could
-run:
+The demo shown in the gif can be run with all available backends.
 
 ```
-cargo run --example termion_demo --release -- --tick-rate 200
+# crossterm
+cargo run --example demo --release -- --tick-rate 200
+# termion
+cargo run --example demo --no-default-features --features=termion --release -- --tick-rate 200
 ```
 
 where `tick-rate` is the UI refresh rate in ms.
 
-The UI code is in [examples/demo/ui.rs](examples/demo/ui.rs) while the
-application state is in [examples/demo/app.rs](examples/demo/app.rs).
-
-Beware that the `termion_demo` only works on Unix platforms. If you are a Windows user,
-you can see the same demo using the `crossterm` backend with the following command:
-
-```
-cargo run --example crossterm_demo --no-default-features --features="crossterm" --release -- --tick-rate 200
-```
+The UI code is in [examples/demo/ui.rs](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/demo/ui.rs) while the
+application state is in [examples/demo/app.rs](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/demo/app.rs).
 
 If the user interface contains glyphs that are not displayed correctly by your terminal, you may want to run
 the demo without those symbols:
 
 ```
-cargo run --example crossterm_demo --no-default-features --features="crossterm" --release -- --tick-rate 200 --enhanced-graphics false
+cargo run --example demo --release -- --tick-rate 200 --enhanced-graphics false
 ```
 
 ### Widgets
 
 The library comes with the following list of widgets:
 
-  * [Block](examples/block.rs)
-  * [Gauge](examples/gauge.rs)
-  * [Sparkline](examples/sparkline.rs)
-  * [Chart](examples/chart.rs)
-  * [BarChart](examples/barchart.rs)
-  * [List](examples/list.rs)
-  * [Table](examples/table.rs)
-  * [Paragraph](examples/paragraph.rs)
-  * [Canvas (with line, point cloud, map)](examples/canvas.rs)
-  * [Tabs](examples/tabs.rs)
+  * [Block](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/block.rs)
+  * [Gauge](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/gauge.rs)
+  * [Sparkline](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/sparkline.rs)
+  * [Chart](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/chart.rs)
+  * [BarChart](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/barchart.rs)
+  * [List](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/list.rs)
+  * [Table](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/table.rs)
+  * [Paragraph](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/paragraph.rs)
+  * [Canvas (with line, point cloud, map)](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/canvas.rs)
+  * [Tabs](https://github.com/fdehau/tui-rs/blob/v0.18.0/examples/tabs.rs)
 
 Click on each item to see the source of the example. Run the examples with with 
-cargo (e.g. to run the demo `cargo run --example demo`), and quit by pressing `q`.
+cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by pressing `q`.
 
-You can run all examples by running `make run-examples`.
+You can run all examples by running `cargo make run-examples` (require
+`cargo-make` that can be installed with `cargo install cargo-make`).
 
 ### Third-party widgets
 
@@ -96,6 +85,7 @@ You can run all examples by running `make run-examples`.
 * [spotify-tui](https://github.com/Rigellute/spotify-tui)
 * [bandwhich](https://github.com/imsnif/bandwhich)
 * [kmon](https://github.com/orhun/kmon)
+* [gpg-tui](https://github.com/orhun/gpg-tui)
 * [ytop](https://github.com/cjbassi/ytop)
 * [zenith](https://github.com/bvaisvil/zenith)
 * [bottom](https://github.com/ClementTsang/bottom)
@@ -109,6 +99,22 @@ You can run all examples by running `make run-examples`.
 * [termchat](https://github.com/lemunozm/termchat)
 * [taskwarrior-tui](https://github.com/kdheepak/taskwarrior-tui)
 * [gping](https://github.com/orf/gping/)
+* [Vector](https://vector.dev)
+* [KDash](https://github.com/kdash-rs/kdash)
+* [xplr](https://github.com/sayanarijit/xplr)
+* [minesweep](https://github.com/cpcloud/minesweep-rs)
+* [Battleship.rs](https://github.com/deepu105/battleship-rs)
+* [termscp](https://github.com/veeso/termscp)
+* [joshuto](https://github.com/kamiyaa/joshuto)
+* [adsb_deku/radar](https://github.com/wcampbell0x2a/adsb_deku#radar-tui)
+* [hoard](https://github.com/Hyde46/hoard)
+* [tokio-console](https://github.com/tokio-rs/console): a diagnostics and debugging tool for asynchronous Rust programs.
+* [hwatch](https://github.com/blacknon/hwatch): a alternative watch command that records the result of command execution and can display its history and diffs.
+* [ytui-music](https://github.com/sudipghimire533/ytui-music): listen to music from youtube inside your terminal.
+* [mqttui](https://github.com/EdJoPaTo/mqttui): subscribe or publish to a MQTT Topic quickly from the terminal.
+* [meteo-tui](https://github.com/16arpi/meteo-tui): french weather via the command line.
+* [picterm](https://github.com/ksk001100/picterm): preview images in your terminal.
+* [gobang](https://github.com/TaKO8Ki/gobang): a cross-platform TUI database management tool.
 
 ### Alternatives
 

examples/barchart.rs

@@ -1,15 +1,19 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     widgets::{BarChart, Block, Borders},
-    Terminal,
+    Frame, Terminal,
 };
 
 struct App<'a> {
@@ -48,85 +52,110 @@ impl<'a> App<'a> {
         }
     }
 
-    fn update(&mut self) {
+    fn on_tick(&mut self) {
         let value = self.data.pop().unwrap();
         self.data.insert(0, value);
     }
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    // Setup event handlers
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    // App
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(2)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(f.size());
-            let barchart = BarChart::default()
-                .block(Block::default().title("Data1").borders(Borders::ALL))
-                .data(&app.data)
-                .bar_width(9)
-                .bar_style(Style::default().fg(Color::Yellow))
-                .value_style(Style::default().fg(Color::Black).bg(Color::Yellow));
-            f.render_widget(barchart, chunks[0]);
-
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[1]);
-
-            let barchart = BarChart::default()
-                .block(Block::default().title("Data2").borders(Borders::ALL))
-                .data(&app.data)
-                .bar_width(5)
-                .bar_gap(3)
-                .bar_style(Style::default().fg(Color::Green))
-                .value_style(
-                    Style::default()
-                        .bg(Color::Green)
-                        .add_modifier(Modifier::BOLD),
-                );
-            f.render_widget(barchart, chunks[0]);
-
-            let barchart = BarChart::default()
-                .block(Block::default().title("Data3").borders(Borders::ALL))
-                .data(&app.data)
-                .bar_style(Style::default().fg(Color::Red))
-                .bar_width(7)
-                .bar_gap(0)
-                .value_style(Style::default().bg(Color::Red))
-                .label_style(
-                    Style::default()
-                        .fg(Color::Cyan)
-                        .add_modifier(Modifier::ITALIC),
-                );
-            f.render_widget(barchart, chunks[1]);
-        })?;
-
-        match events.next()? {
-            Event::Input(input) => {
-                if input == Key::Char('q') {
-                    break;
-                }
-            }
-            Event::Tick => {
-                app.update();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(2)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(f.size());
+    let barchart = BarChart::default()
+        .block(Block::default().title("Data1").borders(Borders::ALL))
+        .data(&app.data)
+        .bar_width(9)
+        .bar_style(Style::default().fg(Color::Yellow))
+        .value_style(Style::default().fg(Color::Black).bg(Color::Yellow));
+    f.render_widget(barchart, chunks[0]);
+
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(chunks[1]);
+
+    let barchart = BarChart::default()
+        .block(Block::default().title("Data2").borders(Borders::ALL))
+        .data(&app.data)
+        .bar_width(5)
+        .bar_gap(3)
+        .bar_style(Style::default().fg(Color::Green))
+        .value_style(
+            Style::default()
+                .bg(Color::Green)
+                .add_modifier(Modifier::BOLD),
+        );
+    f.render_widget(barchart, chunks[0]);
+
+    let barchart = BarChart::default()
+        .block(Block::default().title("Data3").borders(Borders::ALL))
+        .data(&app.data)
+        .bar_style(Style::default().fg(Color::Red))
+        .bar_width(7)
+        .bar_gap(0)
+        .value_style(Style::default().bg(Color::Red))
+        .label_style(
+            Style::default()
+                .fg(Color::Cyan)
+                .add_modifier(Modifier::ITALIC),
+        );
+    f.render_widget(barchart, chunks[1]);
+}

examples/block.rs

@@ -1,86 +1,119 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
-    layout::{Constraint, Direction, Layout},
+    backend::{Backend, CrosstermBackend},
+    layout::{Alignment, Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     text::Span,
     widgets::{Block, BorderType, Borders},
-    Terminal,
+    Frame, Terminal,
 };
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    // Setup event handlers
-    let events = Events::new();
+    // create app and run it
+    let res = run_app(&mut terminal);
 
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{:?}", err)
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
     loop {
-        terminal.draw(|f| {
-            // Wrapping block for a group
-            // Just draw the block and the group on the same area and build the group
-            // with at least a margin of 1
-            let size = f.size();
-            let block = Block::default()
-                .borders(Borders::ALL)
-                .title("Main block with round corners")
-                .border_type(BorderType::Rounded);
-            f.render_widget(block, size);
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(4)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(f.size());
+        terminal.draw(ui)?;
 
-            let top_chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[0]);
-            let block = Block::default()
-                .title(vec![
-                    Span::styled("With", Style::default().fg(Color::Yellow)),
-                    Span::from(" background"),
-                ])
-                .style(Style::default().bg(Color::Green));
-            f.render_widget(block, top_chunks[0]);
-
-            let block = Block::default().title(Span::styled(
-                "Styled title",
-                Style::default()
-                    .fg(Color::White)
-                    .bg(Color::Red)
-                    .add_modifier(Modifier::BOLD),
-            ));
-            f.render_widget(block, top_chunks[1]);
-
-            let bottom_chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(chunks[1]);
-            let block = Block::default().title("With borders").borders(Borders::ALL);
-            f.render_widget(block, bottom_chunks[0]);
-            let block = Block::default()
-                .title("With styled borders and doubled borders")
-                .border_style(Style::default().fg(Color::Cyan))
-                .borders(Borders::LEFT | Borders::RIGHT)
-                .border_type(BorderType::Double);
-            f.render_widget(block, bottom_chunks[1]);
-        })?;
-
-        if let Event::Input(key) = events.next()? {
-            if key == Key::Char('q') {
-                break;
+        if let Event::Key(key) = event::read()? {
+            if let KeyCode::Char('q') = key.code {
+                return Ok(());
             }
         }
     }
-    Ok(())
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>) {
+    // Wrapping block for a group
+    // Just draw the block and the group on the same area and build the group
+    // with at least a margin of 1
+    let size = f.size();
+
+    // Surrounding block
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title("Main block with round corners")
+        .title_alignment(Alignment::Center)
+        .border_type(BorderType::Rounded);
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(4)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(f.size());
+
+    // Top two inner blocks
+    let top_chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(chunks[0]);
+
+    // Top left inner block with green background
+    let block = Block::default()
+        .title(vec![
+            Span::styled("With", Style::default().fg(Color::Yellow)),
+            Span::from(" background"),
+        ])
+        .style(Style::default().bg(Color::Green));
+    f.render_widget(block, top_chunks[0]);
+
+    // Top right inner block with styled title aligned to the right
+    let block = Block::default()
+        .title(Span::styled(
+            "Styled title",
+            Style::default()
+                .fg(Color::White)
+                .bg(Color::Red)
+                .add_modifier(Modifier::BOLD),
+        ))
+        .title_alignment(Alignment::Right);
+    f.render_widget(block, top_chunks[1]);
+
+    // Bottom two inner blocks
+    let bottom_chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(chunks[1]);
+
+    // Bottom left block with all default borders
+    let block = Block::default().title("With borders").borders(Borders::ALL);
+    f.render_widget(block, bottom_chunks[0]);
+
+    // Bottom right block with styled left and right border
+    let block = Block::default()
+        .title("With styled borders and doubled borders")
+        .border_style(Style::default().fg(Color::Cyan))
+        .borders(Borders::LEFT | Borders::RIGHT)
+        .border_type(BorderType::Double);
+    f.render_widget(block, bottom_chunks[1]);
 }

examples/canvas.rs

@@ -1,18 +1,23 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Config, Event, Events};
-use std::{error::Error, io, time::Duration};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout, Rect},
-    style::Color,
+    style::{Color, Style},
+    text::Span,
     widgets::{
         canvas::{Canvas, Map, MapResolution, Rectangle},
         Block, Borders,
     },
-    Terminal,
+    Frame, Terminal,
 };
 
 struct App {
@@ -46,7 +51,7 @@ impl App {
         }
     }
 
-    fn update(&mut self) {
+    fn on_tick(&mut self) {
         if self.ball.x < self.playground.left() as f64
             || self.ball.x + self.ball.width > self.playground.right() as f64
         {
@@ -73,76 +78,103 @@ impl App {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    // Setup event handlers
-    let config = Config {
-        tick_rate: Duration::from_millis(250),
-        ..Default::default()
-    };
-    let events = Events::with_config(config);
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    // App
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(f.size());
-            let canvas = Canvas::default()
-                .block(Block::default().borders(Borders::ALL).title("World"))
-                .paint(|ctx| {
-                    ctx.draw(&Map {
-                        color: Color::White,
-                        resolution: MapResolution::High,
-                    });
-                    ctx.print(app.x, -app.y, "You are here", Color::Yellow);
-                })
-                .x_bounds([-180.0, 180.0])
-                .y_bounds([-90.0, 90.0]);
-            f.render_widget(canvas, chunks[0]);
-            let canvas = Canvas::default()
-                .block(Block::default().borders(Borders::ALL).title("Pong"))
-                .paint(|ctx| {
-                    ctx.draw(&app.ball);
-                })
-                .x_bounds([10.0, 110.0])
-                .y_bounds([10.0, 110.0]);
-            f.render_widget(canvas, chunks[1]);
-        })?;
-
-        match events.next()? {
-            Event::Input(input) => match input {
-                Key::Char('q') => {
-                    break;
-                }
-                Key::Down => {
-                    app.y += 1.0;
-                }
-                Key::Up => {
-                    app.y -= 1.0;
-                }
-                Key::Right => {
-                    app.x += 1.0;
-                }
-                Key::Left => {
-                    app.x -= 1.0;
-                }
-
-                _ => {}
-            },
-            Event::Tick => {
-                app.update();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char('q') => {
+                        return Ok(());
+                    }
+                    KeyCode::Down => {
+                        app.y += 1.0;
+                    }
+                    KeyCode::Up => {
+                        app.y -= 1.0;
+                    }
+                    KeyCode::Right => {
+                        app.x += 1.0;
+                    }
+                    KeyCode::Left => {
+                        app.x -= 1.0;
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(f.size());
+    let canvas = Canvas::default()
+        .block(Block::default().borders(Borders::ALL).title("World"))
+        .paint(|ctx| {
+            ctx.draw(&Map {
+                color: Color::White,
+                resolution: MapResolution::High,
+            });
+            ctx.print(
+                app.x,
+                -app.y,
+                Span::styled("You are here", Style::default().fg(Color::Yellow)),
+            );
+        })
+        .x_bounds([-180.0, 180.0])
+        .y_bounds([-90.0, 90.0]);
+    f.render_widget(canvas, chunks[0]);
+    let canvas = Canvas::default()
+        .block(Block::default().borders(Borders::ALL).title("Pong"))
+        .paint(|ctx| {
+            ctx.draw(&app.ball);
+        })
+        .x_bounds([10.0, 110.0])
+        .y_bounds([10.0, 110.0]);
+    f.render_widget(canvas, chunks[1]);
+}

examples/chart.rs

@@ -1,20 +1,21 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::{
-    event::{Event, Events},
-    SinSignal,
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
 };
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     symbols,
     text::Span,
     widgets::{Axis, Block, Borders, Chart, Dataset, GraphType},
-    Terminal,
+    Frame, Terminal,
 };
 
 const DATA: [(f64, f64); 5] = [(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
@@ -28,6 +29,34 @@ const DATA2: [(f64, f64); 7] = [
     (60.0, 3.0),
 ];
 
+#[derive(Clone)]
+pub struct SinSignal {
+    x: f64,
+    interval: f64,
+    period: f64,
+    scale: f64,
+}
+
+impl SinSignal {
+    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
+        SinSignal {
+            x: 0.0,
+            interval,
+            period,
+            scale,
+        }
+    }
+}
+
+impl Iterator for SinSignal {
+    type Item = (f64, f64);
+    fn next(&mut self) -> Option<Self::Item> {
+        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
+        self.x += self.interval;
+        Some(point)
+    }
+}
+
 struct App {
     signal1: SinSignal,
     data1: Vec<(f64, f64)>,
@@ -51,7 +80,7 @@ impl App {
         }
     }
 
-    fn update(&mut self) {
+    fn on_tick(&mut self) {
         for _ in 0..5 {
             self.data1.remove(0);
         }
@@ -66,181 +95,207 @@ impl App {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    // App
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            let size = f.size();
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .constraints(
-                    [
-                        Constraint::Ratio(1, 3),
-                        Constraint::Ratio(1, 3),
-                        Constraint::Ratio(1, 3),
-                    ]
-                    .as_ref(),
-                )
-                .split(size);
-            let x_labels = vec![
-                Span::styled(
-                    format!("{}", app.window[0]),
-                    Style::default().add_modifier(Modifier::BOLD),
-                ),
-                Span::raw(format!("{}", (app.window[0] + app.window[1]) / 2.0)),
-                Span::styled(
-                    format!("{}", app.window[1]),
-                    Style::default().add_modifier(Modifier::BOLD),
-                ),
-            ];
-            let datasets = vec![
-                Dataset::default()
-                    .name("data2")
-                    .marker(symbols::Marker::Dot)
-                    .style(Style::default().fg(Color::Cyan))
-                    .data(&app.data1),
-                Dataset::default()
-                    .name("data3")
-                    .marker(symbols::Marker::Braille)
-                    .style(Style::default().fg(Color::Yellow))
-                    .data(&app.data2),
-            ];
-
-            let chart = Chart::new(datasets)
-                .block(
-                    Block::default()
-                        .title(Span::styled(
-                            "Chart 1",
-                            Style::default()
-                                .fg(Color::Cyan)
-                                .add_modifier(Modifier::BOLD),
-                        ))
-                        .borders(Borders::ALL),
-                )
-                .x_axis(
-                    Axis::default()
-                        .title("X Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .labels(x_labels)
-                        .bounds(app.window),
-                )
-                .y_axis(
-                    Axis::default()
-                        .title("Y Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .labels(vec![
-                            Span::styled("-20", Style::default().add_modifier(Modifier::BOLD)),
-                            Span::raw("0"),
-                            Span::styled("20", Style::default().add_modifier(Modifier::BOLD)),
-                        ])
-                        .bounds([-20.0, 20.0]),
-                );
-            f.render_widget(chart, chunks[0]);
-
-            let datasets = vec![Dataset::default()
-                .name("data")
-                .marker(symbols::Marker::Braille)
-                .style(Style::default().fg(Color::Yellow))
-                .graph_type(GraphType::Line)
-                .data(&DATA)];
-            let chart = Chart::new(datasets)
-                .block(
-                    Block::default()
-                        .title(Span::styled(
-                            "Chart 2",
-                            Style::default()
-                                .fg(Color::Cyan)
-                                .add_modifier(Modifier::BOLD),
-                        ))
-                        .borders(Borders::ALL),
-                )
-                .x_axis(
-                    Axis::default()
-                        .title("X Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .bounds([0.0, 5.0])
-                        .labels(vec![
-                            Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
-                            Span::raw("2.5"),
-                            Span::styled("5.0", Style::default().add_modifier(Modifier::BOLD)),
-                        ]),
-                )
-                .y_axis(
-                    Axis::default()
-                        .title("Y Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .bounds([0.0, 5.0])
-                        .labels(vec![
-                            Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
-                            Span::raw("2.5"),
-                            Span::styled("5.0", Style::default().add_modifier(Modifier::BOLD)),
-                        ]),
-                );
-            f.render_widget(chart, chunks[1]);
-
-            let datasets = vec![Dataset::default()
-                .name("data")
-                .marker(symbols::Marker::Braille)
-                .style(Style::default().fg(Color::Yellow))
-                .graph_type(GraphType::Line)
-                .data(&DATA2)];
-            let chart = Chart::new(datasets)
-                .block(
-                    Block::default()
-                        .title(Span::styled(
-                            "Chart 3",
-                            Style::default()
-                                .fg(Color::Cyan)
-                                .add_modifier(Modifier::BOLD),
-                        ))
-                        .borders(Borders::ALL),
-                )
-                .x_axis(
-                    Axis::default()
-                        .title("X Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .bounds([0.0, 50.0])
-                        .labels(vec![
-                            Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
-                            Span::raw("25"),
-                            Span::styled("50", Style::default().add_modifier(Modifier::BOLD)),
-                        ]),
-                )
-                .y_axis(
-                    Axis::default()
-                        .title("Y Axis")
-                        .style(Style::default().fg(Color::Gray))
-                        .bounds([0.0, 5.0])
-                        .labels(vec![
-                            Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
-                            Span::raw("2.5"),
-                            Span::styled("5", Style::default().add_modifier(Modifier::BOLD)),
-                        ]),
-                );
-            f.render_widget(chart, chunks[2]);
-        })?;
-
-        match events.next()? {
-            Event::Input(input) => {
-                if input == Key::Char('q') {
-                    break;
-                }
-            }
-            Event::Tick => {
-                app.update();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let size = f.size();
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints(
+            [
+                Constraint::Ratio(1, 3),
+                Constraint::Ratio(1, 3),
+                Constraint::Ratio(1, 3),
+            ]
+            .as_ref(),
+        )
+        .split(size);
+    let x_labels = vec![
+        Span::styled(
+            format!("{}", app.window[0]),
+            Style::default().add_modifier(Modifier::BOLD),
+        ),
+        Span::raw(format!("{}", (app.window[0] + app.window[1]) / 2.0)),
+        Span::styled(
+            format!("{}", app.window[1]),
+            Style::default().add_modifier(Modifier::BOLD),
+        ),
+    ];
+    let datasets = vec![
+        Dataset::default()
+            .name("data2")
+            .marker(symbols::Marker::Dot)
+            .style(Style::default().fg(Color::Cyan))
+            .data(&app.data1),
+        Dataset::default()
+            .name("data3")
+            .marker(symbols::Marker::Braille)
+            .style(Style::default().fg(Color::Yellow))
+            .data(&app.data2),
+    ];
+
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title(Span::styled(
+                    "Chart 1",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                ))
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .labels(x_labels)
+                .bounds(app.window),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .labels(vec![
+                    Span::styled("-20", Style::default().add_modifier(Modifier::BOLD)),
+                    Span::raw("0"),
+                    Span::styled("20", Style::default().add_modifier(Modifier::BOLD)),
+                ])
+                .bounds([-20.0, 20.0]),
+        );
+    f.render_widget(chart, chunks[0]);
+
+    let datasets = vec![Dataset::default()
+        .name("data")
+        .marker(symbols::Marker::Braille)
+        .style(Style::default().fg(Color::Yellow))
+        .graph_type(GraphType::Line)
+        .data(&DATA)];
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title(Span::styled(
+                    "Chart 2",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                ))
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec![
+                    Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
+                    Span::raw("2.5"),
+                    Span::styled("5.0", Style::default().add_modifier(Modifier::BOLD)),
+                ]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec![
+                    Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
+                    Span::raw("2.5"),
+                    Span::styled("5.0", Style::default().add_modifier(Modifier::BOLD)),
+                ]),
+        );
+    f.render_widget(chart, chunks[1]);
+
+    let datasets = vec![Dataset::default()
+        .name("data")
+        .marker(symbols::Marker::Braille)
+        .style(Style::default().fg(Color::Yellow))
+        .graph_type(GraphType::Line)
+        .data(&DATA2)];
+    let chart = Chart::new(datasets)
+        .block(
+            Block::default()
+                .title(Span::styled(
+                    "Chart 3",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                ))
+                .borders(Borders::ALL),
+        )
+        .x_axis(
+            Axis::default()
+                .title("X Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 50.0])
+                .labels(vec![
+                    Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
+                    Span::raw("25"),
+                    Span::styled("50", Style::default().add_modifier(Modifier::BOLD)),
+                ]),
+        )
+        .y_axis(
+            Axis::default()
+                .title("Y Axis")
+                .style(Style::default().fg(Color::Gray))
+                .bounds([0.0, 5.0])
+                .labels(vec![
+                    Span::styled("0", Style::default().add_modifier(Modifier::BOLD)),
+                    Span::raw("2.5"),
+                    Span::styled("5", Style::default().add_modifier(Modifier::BOLD)),
+                ]),
+        );
+    f.render_widget(chart, chunks[2]);
+}

examples/crossterm_demo.rs

@@ -1,108 +0,0 @@
-#[allow(dead_code)]
-mod demo;
-#[allow(dead_code)]
-mod util;
-
-use crate::demo::{ui, App};
-use argh::FromArgs;
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event as CEvent, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
-use std::{
-    error::Error,
-    io::stdout,
-    sync::mpsc,
-    thread,
-    time::{Duration, Instant},
-};
-use tui::{backend::CrosstermBackend, Terminal};
-
-enum Event<I> {
-    Input(I),
-    Tick,
-}
-
-/// Crossterm demo
-#[derive(Debug, FromArgs)]
-struct Cli {
-    /// time in ms between two ticks.
-    #[argh(option, default = "250")]
-    tick_rate: u64,
-    /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
-
-    enable_raw_mode()?;
-
-    let mut stdout = stdout();
-    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
-
-    let backend = CrosstermBackend::new(stdout);
-
-    let mut terminal = Terminal::new(backend)?;
-
-    // Setup input handling
-    let (tx, rx) = mpsc::channel();
-
-    let tick_rate = Duration::from_millis(cli.tick_rate);
-    thread::spawn(move || {
-        let mut last_tick = Instant::now();
-        loop {
-            // poll for tick rate duration, if no events, sent tick event.
-            let timeout = tick_rate
-                .checked_sub(last_tick.elapsed())
-                .unwrap_or_else(|| Duration::from_secs(0));
-            if event::poll(timeout).unwrap() {
-                if let CEvent::Key(key) = event::read().unwrap() {
-                    tx.send(Event::Input(key)).unwrap();
-                }
-            }
-            if last_tick.elapsed() >= tick_rate {
-                tx.send(Event::Tick).unwrap();
-                last_tick = Instant::now();
-            }
-        }
-    });
-
-    let mut app = App::new("Crossterm Demo", cli.enhanced_graphics);
-
-    terminal.clear()?;
-
-    loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
-        match rx.recv()? {
-            Event::Input(event) => match event.code {
-                KeyCode::Char('q') => {
-                    disable_raw_mode()?;
-                    execute!(
-                        terminal.backend_mut(),
-                        LeaveAlternateScreen,
-                        DisableMouseCapture
-                    )?;
-                    terminal.show_cursor()?;
-                    break;
-                }
-                KeyCode::Char(c) => app.on_key(c),
-                KeyCode::Left => app.on_left(),
-                KeyCode::Up => app.on_up(),
-                KeyCode::Right => app.on_right(),
-                KeyCode::Down => app.on_down(),
-                _ => {}
-            },
-            Event::Tick => {
-                app.on_tick();
-            }
-        }
-        if app.should_quit {
-            break;
-        }
-    }
-
-    Ok(())
-}

examples/curses_demo.rs

@@ -1,74 +0,0 @@
-mod demo;
-#[allow(dead_code)]
-mod util;
-
-use crate::demo::{ui, App};
-use argh::FromArgs;
-use std::{
-    error::Error,
-    io,
-    time::{Duration, Instant},
-};
-use tui::{backend::CursesBackend, Terminal};
-
-/// Curses demo
-#[derive(Debug, FromArgs)]
-struct Cli {
-    /// time in ms between two ticks.
-    #[argh(option, default = "250")]
-    tick_rate: u64,
-    /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
-
-    let mut backend =
-        CursesBackend::new().ok_or_else(|| io::Error::new(io::ErrorKind::Other, ""))?;
-    let curses = backend.get_curses_mut();
-    curses.set_echo(false);
-    curses.set_input_timeout(easycurses::TimeoutMode::WaitUpTo(50));
-    curses.set_input_mode(easycurses::InputMode::RawCharacter);
-    curses.set_keypad_enabled(true);
-    let mut terminal = Terminal::new(backend)?;
-    terminal.hide_cursor()?;
-
-    let mut app = App::new("Curses demo", cli.enhanced_graphics);
-
-    let mut last_tick = Instant::now();
-    let tick_rate = Duration::from_millis(cli.tick_rate);
-    loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
-        if let Some(input) = terminal.backend_mut().get_curses_mut().get_input() {
-            match input {
-                easycurses::Input::Character(c) => {
-                    app.on_key(c);
-                }
-                easycurses::Input::KeyUp => {
-                    app.on_up();
-                }
-                easycurses::Input::KeyDown => {
-                    app.on_down();
-                }
-                easycurses::Input::KeyLeft => {
-                    app.on_left();
-                }
-                easycurses::Input::KeyRight => {
-                    app.on_right();
-                }
-                _ => {}
-            };
-        };
-        terminal.backend_mut().get_curses_mut().flush_input();
-        if last_tick.elapsed() > tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-        if app.should_quit {
-            break;
-        }
-    }
-    Ok(())
-}

examples/custom_widget.rs

@@ -1,32 +1,26 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
+    buffer::Buffer,
+    layout::Rect,
     style::Style,
-    widgets::{RenderContext, Widget},
-    Terminal,
+    widgets::Widget,
+    Frame, Terminal,
 };
 
+#[derive(Default)]
 struct Label<'a> {
     text: &'a str,
 }
 
-impl<'a> Default for Label<'a> {
-    fn default() -> Label<'a> {
-        Label { text: "" }
-    }
-}
-
 impl<'a> Widget for Label<'a> {
-    type State = ();
-
-    fn render(self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer
-            .set_string(ctx.area.left(), ctx.area.top(), self.text, Style::default());
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        buf.set_string(area.left(), area.top(), self.text, Style::default());
     }
 }
 
@@ -38,28 +32,46 @@ impl<'a> Label<'a> {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let res = run_app(&mut terminal);
 
-    loop {
-        terminal.draw(|f| {
-            let size = f.size();
-            let label = Label::default().text("Test");
-            f.render_widget(label, size);
-        })?;
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-        if let Event::Input(key) = events.next()? {
-            if key == Key::Char('q') {
-                break;
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    loop {
+        terminal.draw(ui)?;
+
+        if let Event::Key(key) = event::read()? {
+            if let KeyCode::Char('q') = key.code {
+                return Ok(());
+            }
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>) {
+    let size = f.size();
+    let label = Label::default().text("Test");
+    f.render_widget(label, size);
+}

examples/demo/app.rs

@@ -1,4 +1,8 @@
-use crate::util::{RandomSignal, SelectableList, SinSignal, TabsState};
+use rand::{
+    distributions::{Distribution, Uniform},
+    rngs::ThreadRng,
+};
+use tui::widgets::ListState;
 
 const TASKS: [&str; 24] = [
     "Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10",
@@ -62,6 +66,120 @@ const EVENTS: [(&str, u64); 24] = [
     ("B24", 5),
 ];
 
+#[derive(Clone)]
+pub struct RandomSignal {
+    distribution: Uniform<u64>,
+    rng: ThreadRng,
+}
+
+impl RandomSignal {
+    pub fn new(lower: u64, upper: u64) -> RandomSignal {
+        RandomSignal {
+            distribution: Uniform::new(lower, upper),
+            rng: rand::thread_rng(),
+        }
+    }
+}
+
+impl Iterator for RandomSignal {
+    type Item = u64;
+    fn next(&mut self) -> Option<u64> {
+        Some(self.distribution.sample(&mut self.rng))
+    }
+}
+
+#[derive(Clone)]
+pub struct SinSignal {
+    x: f64,
+    interval: f64,
+    period: f64,
+    scale: f64,
+}
+
+impl SinSignal {
+    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
+        SinSignal {
+            x: 0.0,
+            interval,
+            period,
+            scale,
+        }
+    }
+}
+
+impl Iterator for SinSignal {
+    type Item = (f64, f64);
+    fn next(&mut self) -> Option<Self::Item> {
+        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
+        self.x += self.interval;
+        Some(point)
+    }
+}
+
+pub struct TabsState<'a> {
+    pub titles: Vec<&'a str>,
+    pub index: usize,
+}
+
+impl<'a> TabsState<'a> {
+    pub fn new(titles: Vec<&'a str>) -> TabsState {
+        TabsState { titles, index: 0 }
+    }
+    pub fn next(&mut self) {
+        self.index = (self.index + 1) % self.titles.len();
+    }
+
+    pub fn previous(&mut self) {
+        if self.index > 0 {
+            self.index -= 1;
+        } else {
+            self.index = self.titles.len() - 1;
+        }
+    }
+}
+
+pub struct StatefulList<T> {
+    pub state: ListState,
+    pub items: Vec<T>,
+}
+
+impl<T> StatefulList<T> {
+    pub fn with_items(items: Vec<T>) -> StatefulList<T> {
+        StatefulList {
+            state: ListState::default(),
+            items,
+        }
+    }
+
+    pub fn next(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i >= self.items.len() - 1 {
+                    0
+                } else {
+                    i + 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    pub fn previous(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i == 0 {
+                    self.items.len() - 1
+                } else {
+                    i - 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+}
+
 pub struct Signal<S: Iterator> {
     source: S,
     pub points: Vec<S::Item>,
@@ -110,8 +228,8 @@ pub struct App<'a> {
     pub show_chart: bool,
     pub progress: f64,
     pub sparkline: Signal<RandomSignal>,
-    pub tasks: SelectableList<&'a str>,
-    pub logs: Vec<(&'a str, &'a str)>,
+    pub tasks: StatefulList<&'a str>,
+    pub logs: StatefulList<(&'a str, &'a str)>,
     pub signals: Signals,
     pub barchart: Vec<(&'a str, u64)>,
     pub servers: Vec<Server<'a>>,
@@ -137,8 +255,8 @@ impl<'a> App<'a> {
                 points: sparkline_points,
                 tick_rate: 1,
             },
-            tasks: SelectableList::with_items(TASKS.to_vec()),
-            logs: Vec::from(LOGS),
+            tasks: StatefulList::with_items(TASKS.to_vec()),
+            logs: StatefulList::with_items(LOGS.to_vec()),
             signals: Signals {
                 sin1: Signal {
                     source: sin_signal,
@@ -221,8 +339,8 @@ impl<'a> App<'a> {
         self.sparkline.on_tick();
         self.signals.on_tick();
 
-        let log = self.logs.pop().unwrap();
-        self.logs.insert(0, log);
+        let log = self.logs.items.pop().unwrap();
+        self.logs.items.insert(0, log);
 
         let event = self.barchart.pop().unwrap();
         self.barchart.insert(0, event);

examples/demo/crossterm.rs

@@ -0,0 +1,77 @@
+use crate::{app::App, ui};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
+use tui::{
+    backend::{Backend, CrosstermBackend},
+    Terminal,
+};
+
+pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new("Crossterm Demo", enhanced_graphics);
+    let res = run_app(&mut terminal, app, tick_rate);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{:?}", err)
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui::draw(f, &mut app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char(c) => app.on_key(c),
+                    KeyCode::Left => app.on_left(),
+                    KeyCode::Up => app.on_up(),
+                    KeyCode::Right => app.on_right(),
+                    KeyCode::Down => app.on_down(),
+                    _ => {}
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}

examples/demo/main.rs

@@ -0,0 +1,31 @@
+mod app;
+#[cfg(feature = "crossterm")]
+mod crossterm;
+#[cfg(feature = "termion")]
+mod termion;
+mod ui;
+
+#[cfg(feature = "crossterm")]
+use crate::crossterm::run;
+#[cfg(feature = "termion")]
+use crate::termion::run;
+use argh::FromArgs;
+use std::{error::Error, time::Duration};
+
+/// Demo
+#[derive(Debug, FromArgs)]
+struct Cli {
+    /// time in ms between two ticks.
+    #[argh(option, default = "250")]
+    tick_rate: u64,
+    /// whether unicode symbols are used to improve the overall look of the app
+    #[argh(option, default = "true")]
+    enhanced_graphics: bool,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let cli: Cli = argh::from_env();
+    let tick_rate = Duration::from_millis(cli.tick_rate);
+    run(tick_rate, cli.enhanced_graphics)?;
+    Ok(())
+}

examples/demo/mod.rs

@@ -1,3 +0,0 @@
-mod app;
-pub mod ui;
-pub use app::App;

examples/demo/termion.rs

@@ -0,0 +1,80 @@
+use crate::{app::App, ui};
+use std::{error::Error, io, sync::mpsc, thread, time::Duration};
+use termion::{
+    event::Key,
+    input::{MouseTerminal, TermRead},
+    raw::IntoRawMode,
+    screen::AlternateScreen,
+};
+use tui::{
+    backend::{Backend, TermionBackend},
+    Terminal,
+};
+
+pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    let stdout = io::stdout().into_raw_mode()?;
+    let stdout = MouseTerminal::from(stdout);
+    let stdout = AlternateScreen::from(stdout);
+    let backend = TermionBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new("Termion demo", enhanced_graphics);
+    run_app(&mut terminal, app, tick_rate)?;
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> Result<(), Box<dyn Error>> {
+    let events = events(tick_rate);
+    loop {
+        terminal.draw(|f| ui::draw(f, &mut app))?;
+
+        match events.recv()? {
+            Event::Input(key) => match key {
+                Key::Char(c) => app.on_key(c),
+                Key::Up => app.on_up(),
+                Key::Down => app.on_down(),
+                Key::Left => app.on_left(),
+                Key::Right => app.on_right(),
+                _ => {}
+            },
+            Event::Tick => app.on_tick(),
+        }
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}
+
+enum Event {
+    Input(Key),
+    Tick,
+}
+
+fn events(tick_rate: Duration) -> mpsc::Receiver<Event> {
+    let (tx, rx) = mpsc::channel();
+    let keys_tx = tx.clone();
+    thread::spawn(move || {
+        let stdin = io::stdin();
+        for key in stdin.keys().flatten() {
+            if let Err(err) = keys_tx.send(Event::Input(key)) {
+                eprintln!("{}", err);
+                return;
+            }
+        }
+    });
+    thread::spawn(move || loop {
+        if let Err(err) = tx.send(Event::Tick) {
+            eprintln!("{}", err);
+            break;
+        }
+        thread::sleep(tick_rate);
+    });
+    rx
+}

examples/demo/ui.rs

@@ -1,4 +1,4 @@
-use crate::demo::App;
+use crate::app::App;
 use tui::{
     backend::Backend,
     layout::{Constraint, Direction, Layout, Rect},
@@ -140,11 +140,10 @@ where
                 .map(|i| ListItem::new(vec![Spans::from(Span::raw(*i))]))
                 .collect();
             let tasks = List::new(tasks)
-                .select(app.tasks.selected)
-                .block(Block::default().borders(Borders::ALL).title("Tasks"))
+                .block(Block::default().borders(Borders::ALL).title("List"))
                 .highlight_style(Style::default().add_modifier(Modifier::BOLD))
                 .highlight_symbol("> ");
-            f.render_widget(tasks, chunks[0]);
+            f.render_stateful_widget(tasks, chunks[0], &mut app.tasks.state);
 
             // Draw logs
             let info_style = Style::default().fg(Color::Blue);
@@ -153,6 +152,7 @@ where
             let critical_style = Style::default().fg(Color::Red);
             let logs: Vec<ListItem> = app
                 .logs
+                .items
                 .iter()
                 .map(|&(evt, level)| {
                     let s = match level {
@@ -168,8 +168,8 @@ where
                     ListItem::new(content)
                 })
                 .collect();
-            let logs = List::new(logs).block(Block::default().borders(Borders::ALL).title("Logs"));
-            f.render_widget(logs, chunks[1]);
+            let logs = List::new(logs).block(Block::default().borders(Borders::ALL).title("List"));
+            f.render_stateful_widget(logs, chunks[1], &mut app.logs.state);
         }
 
         let barchart = BarChart::default()
@@ -293,7 +293,10 @@ where
             .fg(Color::Magenta)
             .add_modifier(Modifier::BOLD),
     ));
-    let paragraph = Paragraph::new(text).block(block).wrap(Wrap { trim: true });
+    let paragraph = Paragraph::new(text).block(block).wrap(Wrap {
+        trim: true,
+        break_words: false,
+    });
     f.render_widget(paragraph, area);
 }
 
@@ -363,7 +366,11 @@ where
                 } else {
                     Color::Red
                 };
-                ctx.print(server.coords.1, server.coords.0, "X", color);
+                ctx.print(
+                    server.coords.1,
+                    server.coords.0,
+                    Span::styled("X", Style::default().fg(color)),
+                );
             }
         })
         .marker(if app.enhanced_graphics {

examples/gauge.rs

@@ -1,15 +1,20 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
+    text::Span,
     widgets::{Block, Borders, Gauge},
-    Terminal,
+    Frame, Terminal,
 };
 
 struct App {
@@ -24,17 +29,17 @@ impl App {
         App {
             progress1: 0,
             progress2: 0,
-            progress3: 0.0,
+            progress3: 0.45,
             progress4: 0,
         }
     }
 
-    fn update(&mut self) {
-        self.progress1 += 5;
+    fn on_tick(&mut self) {
+        self.progress1 += 1;
         if self.progress1 > 100 {
             self.progress1 = 0;
         }
-        self.progress2 += 10;
+        self.progress2 += 2;
         if self.progress2 > 100 {
             self.progress2 = 0;
         }
@@ -42,7 +47,7 @@ impl App {
         if self.progress3 > 1.0 {
             self.progress3 = 0.0;
         }
-        self.progress4 += 3;
+        self.progress4 += 1;
         if self.progress4 > 100 {
             self.progress4 = 0;
         }
@@ -50,78 +55,112 @@ impl App {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(2)
-                .constraints(
-                    [
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                    ]
-                    .as_ref(),
-                )
-                .split(f.size());
-
-            let gauge = Gauge::default()
-                .block(Block::default().title("Gauge1").borders(Borders::ALL))
-                .gauge_style(Style::default().fg(Color::Yellow))
-                .percent(app.progress1);
-            f.render_widget(gauge, chunks[0]);
-
-            let label = format!("{}/100", app.progress2);
-            let gauge = Gauge::default()
-                .block(Block::default().title("Gauge2").borders(Borders::ALL))
-                .gauge_style(Style::default().fg(Color::Magenta).bg(Color::Green))
-                .percent(app.progress2)
-                .label(label);
-            f.render_widget(gauge, chunks[1]);
-
-            let gauge = Gauge::default()
-                .block(Block::default().title("Gauge3").borders(Borders::ALL))
-                .gauge_style(Style::default().fg(Color::Yellow))
-                .ratio(app.progress3);
-            f.render_widget(gauge, chunks[2]);
-
-            let label = format!("{}/100", app.progress2);
-            let gauge = Gauge::default()
-                .block(Block::default().title("Gauge4"))
-                .gauge_style(
-                    Style::default()
-                        .fg(Color::Cyan)
-                        .add_modifier(Modifier::ITALIC),
-                )
-                .percent(app.progress4)
-                .label(label)
-                .use_unicode(true);
-            f.render_widget(gauge, chunks[3]);
-        })?;
-
-        match events.next()? {
-            Event::Input(input) => {
-                if input == Key::Char('q') {
-                    break;
-                }
-            }
-            Event::Tick => {
-                app.update();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(2)
+        .constraints(
+            [
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+            ]
+            .as_ref(),
+        )
+        .split(f.size());
+
+    let gauge = Gauge::default()
+        .block(Block::default().title("Gauge1").borders(Borders::ALL))
+        .gauge_style(Style::default().fg(Color::Yellow))
+        .percent(app.progress1);
+    f.render_widget(gauge, chunks[0]);
+
+    let label = format!("{}/100", app.progress2);
+    let gauge = Gauge::default()
+        .block(Block::default().title("Gauge2").borders(Borders::ALL))
+        .gauge_style(Style::default().fg(Color::Magenta).bg(Color::Green))
+        .percent(app.progress2)
+        .label(label);
+    f.render_widget(gauge, chunks[1]);
+
+    let label = Span::styled(
+        format!("{:.2}%", app.progress3 * 100.0),
+        Style::default()
+            .fg(Color::Red)
+            .add_modifier(Modifier::ITALIC | Modifier::BOLD),
+    );
+    let gauge = Gauge::default()
+        .block(Block::default().title("Gauge3").borders(Borders::ALL))
+        .gauge_style(Style::default().fg(Color::Yellow))
+        .ratio(app.progress3)
+        .label(label)
+        .use_unicode(true);
+    f.render_widget(gauge, chunks[2]);
+
+    let label = format!("{}/100", app.progress2);
+    let gauge = Gauge::default()
+        .block(Block::default().title("Gauge4"))
+        .gauge_style(
+            Style::default()
+                .fg(Color::Cyan)
+                .add_modifier(Modifier::ITALIC),
+        )
+        .percent(app.progress4)
+        .label(label);
+    f.render_widget(gauge, chunks[3]);
+}

examples/layout.rs

@@ -1,52 +1,70 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     widgets::{Block, Borders},
-    Terminal,
+    Frame, Terminal,
 };
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let res = run_app(&mut terminal);
 
-    loop {
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .constraints(
-                    [
-                        Constraint::Percentage(10),
-                        Constraint::Percentage(80),
-                        Constraint::Percentage(10),
-                    ]
-                    .as_ref(),
-                )
-                .split(f.size());
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-            let block = Block::default().title("Block").borders(Borders::ALL);
-            f.render_widget(block, chunks[0]);
-            let block = Block::default().title("Block 2").borders(Borders::ALL);
-            f.render_widget(block, chunks[2]);
-        })?;
-
-        if let Event::Input(input) = events.next()? {
-            if let Key::Char('q') = input {
-                break;
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f))?;
+
+        if let Event::Key(key) = event::read()? {
+            if let KeyCode::Char('q') = key.code {
+                return Ok(());
+            }
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints(
+            [
+                Constraint::Percentage(10),
+                Constraint::Percentage(80),
+                Constraint::Percentage(10),
+            ]
+            .as_ref(),
+        )
+        .split(f.size());
+
+    let block = Block::default().title("Block").borders(Borders::ALL);
+    f.render_widget(block, chunks[0]);
+    let block = Block::default().title("Block 2").borders(Borders::ALL);
+    f.render_widget(block, chunks[2]);
+}

examples/list.rs

@@ -1,21 +1,68 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::{
-    event::{Event, Events},
-    SelectableList,
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
 };
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Corner, Direction, Layout},
     style::{Color, Modifier, Style},
     text::{Span, Spans},
-    widgets::{Block, Borders, List, ListItem},
-    Terminal,
+    widgets::{Block, Borders, List, ListItem, ListState},
+    Frame, Terminal,
 };
 
+struct StatefulList<T> {
+    state: ListState,
+    items: Vec<T>,
+}
+
+impl<T> StatefulList<T> {
+    fn with_items(items: Vec<T>) -> StatefulList<T> {
+        StatefulList {
+            state: ListState::default(),
+            items,
+        }
+    }
+
+    fn next(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i >= self.items.len() - 1 {
+                    0
+                } else {
+                    i + 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    fn previous(&mut self) {
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i == 0 {
+                    self.items.len() - 1
+                } else {
+                    i - 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
+    }
+
+    fn unselect(&mut self) {
+        self.state.select(None);
+    }
+}
+
 /// This struct holds the current state of the app. In particular, it has the `items` field which is a wrapper
 /// around `ListState`. Keeping track of the items state let us render the associated widget with its state
 /// and have access to features such as natural scrolling.
@@ -23,14 +70,14 @@ use tui::{
 /// Check the event handling at the bottom to see how to change the state on incoming events.
 /// Check the drawing logic for items on how to specify the highlighting style for selected items.
 struct App<'a> {
-    items: SelectableList<(&'a str, usize)>,
+    items: StatefulList<(&'a str, usize)>,
     events: Vec<(&'a str, &'a str)>,
 }
 
 impl<'a> App<'a> {
     fn new() -> App<'a> {
         App {
-            items: SelectableList::with_items(vec![
+            items: StatefulList::with_items(vec![
                 ("Item0", 1),
                 ("Item1", 2),
                 ("Item2", 1),
@@ -90,135 +137,150 @@ impl<'a> App<'a> {
 
     /// Rotate through the event list.
     /// This only exists to simulate some kind of "progress"
-    fn advance(&mut self) {
+    fn on_tick(&mut self) {
         let event = self.events.remove(0);
         self.events.push(event);
     }
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    // Create a new app with some exapmle state
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            // Create two chunks with equal horizontal screen space
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(f.size());
-
-            // Iterate through all elements in the `items` app and append some debug text to it.
-            let items: Vec<ListItem> = app
-                .items
-                .items
-                .iter()
-                .map(|i| {
-                    let mut lines = vec![Spans::from(i.0)];
-                    for _ in 0..i.1 {
-                        lines.push(Spans::from(Span::styled(
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
-                            Style::default().add_modifier(Modifier::ITALIC),
-                        )));
-                    }
-                    ListItem::new(lines).style(Style::default().fg(Color::Black).bg(Color::White))
-                })
-                .collect();
-
-            // Create a List from all list items and highlight the currently selected one
-            let items = List::new(items)
-                .block(Block::default().borders(Borders::ALL).title("List"))
-                .select(app.items.selected)
-                .highlight_style(
-                    Style::default()
-                        .bg(Color::LightGreen)
-                        .add_modifier(Modifier::BOLD),
-                )
-                .highlight_symbol(">> ");
-
-            // We can now render the item list
-            f.render_widget(items, chunks[0]);
-
-            // Let's do the same for the events.
-            // The event list doesn't have any state and only displays the current state of the list.
-            let events: Vec<ListItem> = app
-                .events
-                .iter()
-                .rev()
-                .map(|&(event, level)| {
-                    // Colorcode the level depending on its type
-                    let s = match level {
-                        "CRITICAL" => Style::default().fg(Color::Red),
-                        "ERROR" => Style::default().fg(Color::Magenta),
-                        "WARNING" => Style::default().fg(Color::Yellow),
-                        "INFO" => Style::default().fg(Color::Blue),
-                        _ => Style::default(),
-                    };
-                    // Add a example datetime and apply proper spacing between them
-                    let header = Spans::from(vec![
-                        Span::styled(format!("{:<9}", level), s),
-                        Span::raw(" "),
-                        Span::styled(
-                            "2020-01-01 10:00:00",
-                            Style::default().add_modifier(Modifier::ITALIC),
-                        ),
-                    ]);
-                    // The event gets it's own line
-                    let log = Spans::from(vec![Span::raw(event)]);
-
-                    // Here several things happen:
-                    // 1. Add a `---` spacing line above the final list entry
-                    // 2. Add the Level + datetime
-                    // 3. Add a spacer line
-                    // 4. Add the actual event
-                    ListItem::new(vec![
-                        Spans::from("-".repeat(chunks[1].width as usize)),
-                        header,
-                        Spans::from(""),
-                        log,
-                    ])
-                })
-                .collect();
-            let events_list = List::new(events)
-                .block(Block::default().borders(Borders::ALL).title("List"))
-                .start_corner(Corner::BottomLeft);
-            f.render_widget(events_list, chunks[1]);
-        })?;
-
-        // This is a simple example on how to handle events
-        // 1. This breaks the loop and exits the program on `q` button press.
-        // 2. The `up`/`down` keys change the currently selected item in the App's `items` list.
-        // 3. `left` unselects the current item.
-        match events.next()? {
-            Event::Input(input) => match input {
-                Key::Char('q') => {
-                    break;
-                }
-                Key::Left => {
-                    app.items.unselect();
-                }
-                Key::Down => {
-                    app.items.next();
-                }
-                Key::Up => {
-                    app.items.previous();
-                }
-                _ => {}
-            },
-            Event::Tick => {
-                app.advance();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &mut app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                match key.code {
+                    KeyCode::Char('q') => return Ok(()),
+                    KeyCode::Left => app.items.unselect(),
+                    KeyCode::Down => app.items.next(),
+                    KeyCode::Up => app.items.previous(),
+                    _ => {}
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+    // Create two chunks with equal horizontal screen space
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(f.size());
+
+    // Iterate through all elements in the `items` app and append some debug text to it.
+    let items: Vec<ListItem> = app
+        .items
+        .items
+        .iter()
+        .map(|i| {
+            let mut lines = vec![Spans::from(i.0)];
+            for _ in 0..i.1 {
+                lines.push(Spans::from(Span::styled(
+                    "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+                    Style::default().add_modifier(Modifier::ITALIC),
+                )));
+            }
+            ListItem::new(lines).style(Style::default().fg(Color::Black).bg(Color::White))
+        })
+        .collect();
+
+    // Create a List from all list items and highlight the currently selected one
+    let items = List::new(items)
+        .block(Block::default().borders(Borders::ALL).title("List"))
+        .highlight_style(
+            Style::default()
+                .bg(Color::LightGreen)
+                .add_modifier(Modifier::BOLD),
+        )
+        .highlight_symbol(">> ");
+
+    // We can now render the item list
+    f.render_stateful_widget(items, chunks[0], &mut app.items.state);
+
+    // Let's do the same for the events.
+    // The event list doesn't have any state and only displays the current state of the list.
+    let events: Vec<ListItem> = app
+        .events
+        .iter()
+        .rev()
+        .map(|&(event, level)| {
+            // Colorcode the level depending on its type
+            let s = match level {
+                "CRITICAL" => Style::default().fg(Color::Red),
+                "ERROR" => Style::default().fg(Color::Magenta),
+                "WARNING" => Style::default().fg(Color::Yellow),
+                "INFO" => Style::default().fg(Color::Blue),
+                _ => Style::default(),
+            };
+            // Add a example datetime and apply proper spacing between them
+            let header = Spans::from(vec![
+                Span::styled(format!("{:<9}", level), s),
+                Span::raw(" "),
+                Span::styled(
+                    "2020-01-01 10:00:00",
+                    Style::default().add_modifier(Modifier::ITALIC),
+                ),
+            ]);
+            // The event gets its own line
+            let log = Spans::from(vec![Span::raw(event)]);
+
+            // Here several things happen:
+            // 1. Add a `---` spacing line above the final list entry
+            // 2. Add the Level + datetime
+            // 3. Add a spacer line
+            // 4. Add the actual event
+            ListItem::new(vec![
+                Spans::from("-".repeat(chunks[1].width as usize)),
+                header,
+                Spans::from(""),
+                log,
+            ])
+        })
+        .collect();
+    let events_list = List::new(events)
+        .block(Block::default().borders(Borders::ALL).title("List"))
+        .start_corner(Corner::BottomLeft);
+    f.render_widget(events_list, chunks[1]);
+}

examples/panic.rs

@@ -0,0 +1,142 @@
+//! How to use a panic hook to reset the terminal before printing the panic to
+//! the terminal.
+//!
+//! When exiting normally or when handling `Result::Err`, we can reset the
+//! terminal manually at the end of `main` just before we print the error.
+//!
+//! Because a panic interrupts the normal control flow, manually resetting the
+//! terminal at the end of `main` won't do us any good. Instead, we need to
+//! make sure to set up a panic hook that first resets the terminal before
+//! handling the panic. This both reuses the standard panic hook to ensure a
+//! consistent panic handling UX and properly resets the terminal to not
+//! distort the output.
+//!
+//! That's why this example is set up to show both situations, with and without
+//! the chained panic hook, to see the difference.
+
+#![deny(clippy::all)]
+#![warn(clippy::pedantic, clippy::nursery)]
+
+use std::error::Error;
+use std::io;
+
+use crossterm::event::{self, Event, KeyCode};
+use crossterm::terminal::{disable_raw_mode, enable_raw_mode};
+use crossterm::terminal::{EnterAlternateScreen, LeaveAlternateScreen};
+
+use tui::backend::{Backend, CrosstermBackend};
+use tui::layout::Alignment;
+use tui::text::Spans;
+use tui::widgets::{Block, Borders, Paragraph};
+use tui::{Frame, Terminal};
+
+type Result<T> = std::result::Result<T, Box<dyn Error>>;
+
+#[derive(Default)]
+struct App {
+    hook_enabled: bool,
+}
+
+impl App {
+    fn chain_hook(&mut self) {
+        let original_hook = std::panic::take_hook();
+
+        std::panic::set_hook(Box::new(move |panic| {
+            reset_terminal().unwrap();
+            original_hook(panic);
+        }));
+
+        self.hook_enabled = true;
+    }
+}
+
+fn main() -> Result<()> {
+    let mut terminal = init_terminal()?;
+
+    let mut app = App::default();
+    let res = run_tui(&mut terminal, &mut app);
+
+    reset_terminal()?;
+
+    if let Err(err) = res {
+        println!("{:?}", err);
+    }
+
+    Ok(())
+}
+
+/// Initializes the terminal.
+fn init_terminal() -> Result<Terminal<CrosstermBackend<io::Stdout>>> {
+    crossterm::execute!(io::stdout(), EnterAlternateScreen)?;
+    enable_raw_mode()?;
+
+    let backend = CrosstermBackend::new(io::stdout());
+
+    let mut terminal = Terminal::new(backend)?;
+    terminal.hide_cursor()?;
+
+    Ok(terminal)
+}
+
+/// Resets the terminal.
+fn reset_terminal() -> Result<()> {
+    disable_raw_mode()?;
+    crossterm::execute!(io::stdout(), LeaveAlternateScreen)?;
+
+    Ok(())
+}
+
+/// Runs the TUI loop.
+fn run_tui<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, app))?;
+
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('p') => {
+                    panic!("intentional demo panic");
+                }
+
+                KeyCode::Char('e') => {
+                    app.chain_hook();
+                }
+
+                _ => {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+/// Render the TUI.
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let text = vec![
+        if app.hook_enabled {
+            Spans::from("HOOK IS CURRENTLY **ENABLED**")
+        } else {
+            Spans::from("HOOK IS CURRENTLY **DISABLED**")
+        },
+        Spans::from(""),
+        Spans::from("press `p` to panic"),
+        Spans::from("press `e` to enable the terminal-resetting panic hook"),
+        Spans::from("press any other key to quit without panic"),
+        Spans::from(""),
+        Spans::from("when you panic without the chained hook,"),
+        Spans::from("you will likely have to reset your terminal afterwards"),
+        Spans::from("with the `reset` command"),
+        Spans::from(""),
+        Spans::from("with the chained panic hook enabled,"),
+        Spans::from("you should see the panic report as you would without tui"),
+        Spans::from(""),
+        Spans::from("try first without the panic handler to see the difference"),
+    ];
+
+    let b = Block::default()
+        .title("Panic Handler Demo")
+        .borders(Borders::ALL);
+
+    let p = Paragraph::new(text).block(b).alignment(Alignment::Center);
+
+    f.render_widget(p, f.size());
+}

examples/paragraph.rs

@@ -1,111 +1,180 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
+};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Alignment, Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     text::{Span, Spans},
     widgets::{Block, Borders, Paragraph, Wrap},
-    Terminal,
+    Frame, Terminal,
 };
 
+struct App {
+    scroll: u16,
+}
+
+impl App {
+    fn new() -> App {
+        App { scroll: 0 }
+    }
+
+    fn on_tick(&mut self) {
+        self.scroll += 1;
+        self.scroll %= 10;
+    }
+}
+
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    let mut scroll: u16 = 0;
-    loop {
-        terminal.draw(|f| {
-            let size = f.size();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-            // Words made "loooong" to demonstrate line breaking.
-            let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-            let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
-            long_line.push('\n');
-
-            let block = Block::default()
-                .style(Style::default().bg(Color::White).fg(Color::Black));
-            f.render_widget(block, size);
-
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(5)
-                .constraints(
-                    [
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                        Constraint::Percentage(25),
-                    ]
-                    .as_ref(),
-                )
-                .split(size);
-
-            let text = vec![
-                Spans::from("This is a line "),
-                Spans::from(Span::styled("This is a line   ", Style::default().fg(Color::Red))),
-                Spans::from(Span::styled("This is a line", Style::default().bg(Color::Blue))),
-                Spans::from(Span::styled(
-                    "This is a longer line",
-                    Style::default().add_modifier(Modifier::CROSSED_OUT),
-                )),
-                Spans::from(Span::styled(&long_line, Style::default().bg(Color::Green))),
-                Spans::from(Span::styled(
-                    "This is a line",
-                    Style::default().fg(Color::Green).add_modifier(Modifier::ITALIC),
-                )),
-            ];
-
-            let create_block = |title| {
-                Block::default()
-                    .borders(Borders::ALL)
-                    .style(Style::default().bg(Color::White).fg(Color::Black))
-                    .title(Span::styled(title, Style::default().add_modifier(Modifier::BOLD)))
-            };
-            let paragraph = Paragraph::new(text.clone())
-                .style(Style::default().bg(Color::White).fg(Color::Black))
-                .block(create_block("Left, no wrap"))
-                .alignment(Alignment::Left);
-            f.render_widget(paragraph, chunks[0]);
-            let paragraph = Paragraph::new(text.clone())
-                .style(Style::default().bg(Color::White).fg(Color::Black))
-                .block(create_block("Left, wrap"))
-                .alignment(Alignment::Left)
-                .wrap(Wrap { trim: true });
-            f.render_widget(paragraph, chunks[1]);
-            let paragraph = Paragraph::new(text.clone())
-                .style(Style::default().bg(Color::White).fg(Color::Black))
-                .block(create_block("Center, wrap"))
-                .alignment(Alignment::Center)
-                .wrap(Wrap { trim: true })
-                .scroll((scroll, 0));
-            f.render_widget(paragraph, chunks[2]);
-            let paragraph = Paragraph::new(text)
-                .style(Style::default().bg(Color::White).fg(Color::Black))
-                .block(create_block("Right, wrap"))
-                .alignment(Alignment::Right)
-                .wrap(Wrap { trim: true });
-            f.render_widget(paragraph, chunks[3]);
-        })?;
-
-        scroll += 1;
-        scroll %= 10;
-
-        if let Event::Input(key) = events.next()? {
-            if key == Key::Char('q') {
-                break;
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
+
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let size = f.size();
+
+    // Words made "loooong" to demonstrate line breaking.
+    let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
+    let mut long_line = s.repeat(usize::from(size.width) / s.len() + 4);
+    long_line.push('\n');
+
+    let block = Block::default().style(Style::default().bg(Color::White).fg(Color::Black));
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(5)
+        .constraints(
+            [
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+                Constraint::Percentage(25),
+            ]
+            .as_ref(),
+        )
+        .split(size);
+
+    let text = vec![
+        Spans::from("This is a line "),
+        Spans::from(Span::styled(
+            "This is a line   ",
+            Style::default().fg(Color::Red),
+        )),
+        Spans::from(Span::styled(
+            "This is a line",
+            Style::default().bg(Color::Blue),
+        )),
+        Spans::from(Span::styled(
+            "This is a longer line",
+            Style::default().add_modifier(Modifier::CROSSED_OUT),
+        )),
+        Spans::from(Span::styled(&long_line, Style::default().bg(Color::Green))),
+        Spans::from(Span::styled(
+            "This is a line",
+            Style::default()
+                .fg(Color::Green)
+                .add_modifier(Modifier::ITALIC),
+        )),
+    ];
+
+    let create_block = |title| {
+        Block::default()
+            .borders(Borders::ALL)
+            .style(Style::default().bg(Color::White).fg(Color::Black))
+            .title(Span::styled(
+                title,
+                Style::default().add_modifier(Modifier::BOLD),
+            ))
+    };
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().bg(Color::White).fg(Color::Black))
+        .block(create_block("Left, no wrap"))
+        .alignment(Alignment::Left);
+    f.render_widget(paragraph, chunks[0]);
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().bg(Color::White).fg(Color::Black))
+        .block(create_block("Left, wrap"))
+        .alignment(Alignment::Left)
+        .wrap(Wrap {
+            trim: true,
+            break_words: false,
+        });
+    f.render_widget(paragraph, chunks[1]);
+    let paragraph = Paragraph::new(text.clone())
+        .style(Style::default().bg(Color::White).fg(Color::Black))
+        .block(create_block("Center, wrap"))
+        .alignment(Alignment::Center)
+        .wrap(Wrap {
+            trim: true,
+            break_words: false,
+        })
+        .scroll((app.scroll, 0));
+    f.render_widget(paragraph, chunks[2]);
+    let paragraph = Paragraph::new(text)
+        .style(Style::default().bg(Color::White).fg(Color::Black))
+        .block(create_block("Right, wrap (break words)"))
+        .alignment(Alignment::Right)
+        .wrap(Wrap {
+            trim: true,
+            break_words: true,
+        });
+    f.render_widget(paragraph, chunks[3]);
+}

examples/popup.rs

@@ -1,20 +1,109 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Alignment, Constraint, Direction, Layout, Rect},
     style::{Color, Modifier, Style},
-    text::{Span, Spans},
+    text::Span,
     widgets::{Block, Borders, Clear, Paragraph, Wrap},
-    Terminal,
+    Frame, Terminal,
 };
 
-/// helper function to create a centered rect using up
-/// certain percentage of the available rect `r`
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+
+struct App {
+    show_popup: bool,
+}
+
+impl App {
+    fn new() -> App {
+        App { show_popup: false }
+    }
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // create app and run it
+    let app = App::new();
+    let res = run_app(&mut terminal, app);
+
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    if let Err(err) = res {
+        println!("{:?}", err)
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('q') => return Ok(()),
+                KeyCode::Char('p') => app.show_popup = !app.show_popup,
+                _ => {}
+            }
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let size = f.size();
+
+    let chunks = Layout::default()
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)].as_ref())
+        .split(size);
+
+    let text = if app.show_popup {
+        "Press p to close the popup"
+    } else {
+        "Press p to show the popup"
+    };
+    let paragraph = Paragraph::new(Span::styled(
+        text,
+        Style::default().add_modifier(Modifier::SLOW_BLINK),
+    ))
+    .alignment(Alignment::Center)
+    .wrap(Wrap {
+        trim: true,
+        break_words: false,
+    });
+    f.render_widget(paragraph, chunks[0]);
+
+    let block = Block::default()
+        .title("Content")
+        .borders(Borders::ALL)
+        .style(Style::default().bg(Color::Blue));
+    f.render_widget(block, chunks[1]);
+
+    if app.show_popup {
+        let block = Block::default().title("Popup").borders(Borders::ALL);
+        let area = centered_rect(60, 20, size);
+        f.render_widget(Clear, area); //this clears out the background
+        f.render_widget(block, area);
+    }
+}
+
+/// helper function to create a centered rect using up certain percentage of the available rect `r`
 fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
     let popup_layout = Layout::default()
         .direction(Direction::Vertical)
@@ -40,67 +129,3 @@ fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
         )
         .split(popup_layout[1])[1]
 }
-
-fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    let events = Events::new();
-
-    loop {
-        terminal.draw(|f| {
-            let size = f.size();
-
-            let chunks = Layout::default()
-                .direction(Direction::Horizontal)
-                .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
-                .split(size);
-
-                let s = "Veeeeeeeeeeeeeeeery    loooooooooooooooooong   striiiiiiiiiiiiiiiiiiiiiiiiiing.   ";
-                let mut long_line = s.repeat(usize::from(size.width)*usize::from(size.height)/300);
-                long_line.push('\n');
-
-            let text = vec![
-                Spans::from("This is a line "),
-                Spans::from(Span::styled("This is a line   ", Style::default().fg(Color::Red))),
-                Spans::from(Span::styled("This is a line", Style::default().bg(Color::Blue))),
-                Spans::from(Span::styled(
-                    "This is a longer line\n",
-                    Style::default().add_modifier(Modifier::CROSSED_OUT),
-                )),
-                Spans::from(Span::styled(&long_line, Style::default().bg(Color::Green))),
-                Spans::from(Span::styled(
-                    "This is a line\n",
-                    Style::default().fg(Color::Green).add_modifier(Modifier::ITALIC),
-                )),
-            ];
-
-            let paragraph = Paragraph::new(text.clone())
-                .block(Block::default().title("Left Block").borders(Borders::ALL))
-                .alignment(Alignment::Left).wrap(Wrap { trim: true });
-            f.render_widget(paragraph, chunks[0]);
-
-            let paragraph = Paragraph::new(text)
-                .block(Block::default().title("Right Block").borders(Borders::ALL))
-                .alignment(Alignment::Left).wrap(Wrap { trim: true });
-            f.render_widget(paragraph, chunks[1]);
-
-            let block = Block::default().title("Popup").borders(Borders::ALL);
-            let area = centered_rect(60, 20, size);
-            f.render_widget(Clear, area); //this clears out the background
-            f.render_widget(block, area);
-        })?;
-
-        if let Event::Input(input) = events.next()? {
-            if let Key::Char('q') = input {
-                break;
-            }
-        }
-    }
-
-    Ok(())
-}

examples/rustbox_demo.rs

@@ -1,68 +0,0 @@
-mod demo;
-#[allow(dead_code)]
-mod util;
-
-use crate::demo::{ui, App};
-use argh::FromArgs;
-use rustbox::keyboard::Key;
-use std::{
-    error::Error,
-    time::{Duration, Instant},
-};
-use tui::{backend::RustboxBackend, Terminal};
-
-/// Rustbox demo
-#[derive(Debug, FromArgs)]
-struct Cli {
-    /// time in ms between two ticks.
-    #[argh(option, default = "250")]
-    tick_rate: u64,
-    /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
-
-    let backend = RustboxBackend::new()?;
-    let mut terminal = Terminal::new(backend)?;
-
-    let mut app = App::new("Rustbox demo", cli.enhanced_graphics);
-
-    let mut last_tick = Instant::now();
-    let tick_rate = Duration::from_millis(cli.tick_rate);
-    loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
-        if let Ok(rustbox::Event::KeyEvent(key)) =
-            terminal.backend().rustbox().peek_event(tick_rate, false)
-        {
-            match key {
-                Key::Char(c) => {
-                    app.on_key(c);
-                }
-                Key::Up => {
-                    app.on_up();
-                }
-                Key::Down => {
-                    app.on_down();
-                }
-                Key::Left => {
-                    app.on_left();
-                }
-                Key::Right => {
-                    app.on_right();
-                }
-                _ => {}
-            }
-        }
-        if last_tick.elapsed() > tick_rate {
-            app.on_tick();
-            last_tick = Instant::now();
-        }
-        if app.should_quit {
-            break;
-        }
-    }
-    Ok(())
-}

examples/sparkline.rs

@@ -1,20 +1,47 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::{
-    event::{Event, Events},
-    RandomSignal,
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use rand::{
+    distributions::{Distribution, Uniform},
+    rngs::ThreadRng,
+};
+use std::{
+    error::Error,
+    io,
+    time::{Duration, Instant},
 };
-use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Style},
     widgets::{Block, Borders, Sparkline},
-    Terminal,
+    Frame, Terminal,
 };
 
+#[derive(Clone)]
+pub struct RandomSignal {
+    distribution: Uniform<u64>,
+    rng: ThreadRng,
+}
+
+impl RandomSignal {
+    pub fn new(lower: u64, upper: u64) -> RandomSignal {
+        RandomSignal {
+            distribution: Uniform::new(lower, upper),
+            rng: rand::thread_rng(),
+        }
+    }
+}
+
+impl Iterator for RandomSignal {
+    type Item = u64;
+    fn next(&mut self) -> Option<u64> {
+        Some(self.distribution.sample(&mut self.rng))
+    }
+}
+
 struct App {
     signal: RandomSignal,
     data1: Vec<u64>,
@@ -36,7 +63,7 @@ impl App {
         }
     }
 
-    fn update(&mut self) {
+    fn on_tick(&mut self) {
         let value = self.signal.next().unwrap();
         self.data1.pop();
         self.data1.insert(0, value);
@@ -50,75 +77,100 @@ impl App {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    // Setup event handlers
-    let events = Events::new();
+    // create app and run it
+    let tick_rate = Duration::from_millis(250);
+    let app = App::new();
+    let res = run_app(&mut terminal, app, tick_rate);
 
-    // Create default app state
-    let mut app = App::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    loop {
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(2)
-                .constraints(
-                    [
-                        Constraint::Length(3),
-                        Constraint::Length(3),
-                        Constraint::Length(7),
-                        Constraint::Min(0),
-                    ]
-                    .as_ref(),
-                )
-                .split(f.size());
-            let sparkline = Sparkline::default()
-                .block(
-                    Block::default()
-                        .title("Data1")
-                        .borders(Borders::LEFT | Borders::RIGHT),
-                )
-                .data(&app.data1)
-                .style(Style::default().fg(Color::Yellow));
-            f.render_widget(sparkline, chunks[0]);
-            let sparkline = Sparkline::default()
-                .block(
-                    Block::default()
-                        .title("Data2")
-                        .borders(Borders::LEFT | Borders::RIGHT),
-                )
-                .data(&app.data2)
-                .style(Style::default().bg(Color::Green));
-            f.render_widget(sparkline, chunks[1]);
-            // Multiline
-            let sparkline = Sparkline::default()
-                .block(
-                    Block::default()
-                        .title("Data3")
-                        .borders(Borders::LEFT | Borders::RIGHT),
-                )
-                .data(&app.data3)
-                .style(Style::default().fg(Color::Red));
-            f.render_widget(sparkline, chunks[2]);
-        })?;
-
-        match events.next()? {
-            Event::Input(input) => {
-                if input == Key::Char('q') {
-                    break;
-                }
-            }
-            Event::Tick => {
-                app.update();
-            }
-        }
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    mut app: App,
+    tick_rate: Duration,
+) -> io::Result<()> {
+    let mut last_tick = Instant::now();
+    loop {
+        terminal.draw(|f| ui(f, &app))?;
+
+        let timeout = tick_rate
+            .checked_sub(last_tick.elapsed())
+            .unwrap_or_else(|| Duration::from_secs(0));
+        if crossterm::event::poll(timeout)? {
+            if let Event::Key(key) = event::read()? {
+                if let KeyCode::Char('q') = key.code {
+                    return Ok(());
+                }
+            }
+        }
+        if last_tick.elapsed() >= tick_rate {
+            app.on_tick();
+            last_tick = Instant::now();
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(2)
+        .constraints(
+            [
+                Constraint::Length(3),
+                Constraint::Length(3),
+                Constraint::Length(7),
+                Constraint::Min(0),
+            ]
+            .as_ref(),
+        )
+        .split(f.size());
+    let sparkline = Sparkline::default()
+        .block(
+            Block::default()
+                .title("Data1")
+                .borders(Borders::LEFT | Borders::RIGHT),
+        )
+        .data(&app.data1)
+        .style(Style::default().fg(Color::Yellow));
+    f.render_widget(sparkline, chunks[0]);
+    let sparkline = Sparkline::default()
+        .block(
+            Block::default()
+                .title("Data2")
+                .borders(Borders::LEFT | Borders::RIGHT),
+        )
+        .data(&app.data2)
+        .style(Style::default().bg(Color::Green));
+    f.render_widget(sparkline, chunks[1]);
+    // Multiline
+    let sparkline = Sparkline::default()
+        .block(
+            Block::default()
+                .title("Data3")
+                .borders(Borders::LEFT | Borders::RIGHT),
+        )
+        .data(&app.data3)
+        .style(Style::default().fg(Color::Red));
+    f.render_widget(sparkline, chunks[2]);
+}

examples/table.rs

@@ -1,26 +1,26 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Layout},
     style::{Color, Modifier, Style},
-    widgets::{Block, Borders, Cell, Row, Table},
-    Terminal,
+    widgets::{Block, Borders, Cell, Row, Table, TableState},
+    Frame, Terminal,
 };
 
-pub struct SelectableTable<'a> {
-    selected: Option<usize>,
+struct App<'a> {
+    state: TableState,
     items: Vec<Vec<&'a str>>,
 }
 
-impl<'a> SelectableTable<'a> {
-    fn new() -> SelectableTable<'a> {
-        SelectableTable {
-            selected: None,
+impl<'a> App<'a> {
+    fn new() -> App<'a> {
+        App {
+            state: TableState::default(),
             items: vec![
                 vec!["Row11", "Row12", "Row13"],
                 vec!["Row21", "Row22", "Row23"],
@@ -44,90 +44,112 @@ impl<'a> SelectableTable<'a> {
             ],
         }
     }
-
     pub fn next(&mut self) {
-        self.selected = self
-            .selected
-            .map(|i| if i >= self.items.len() - 1 { 0 } else { i + 1 })
-            .or(Some(0));
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i >= self.items.len() - 1 {
+                    0
+                } else {
+                    i + 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
     }
 
     pub fn previous(&mut self) {
-        self.selected = self
-            .selected
-            .map(|i| if i == 0 { self.items.len() - 1 } else { i - 1 })
-            .or(Some(0));
+        let i = match self.state.selected() {
+            Some(i) => {
+                if i == 0 {
+                    self.items.len() - 1
+                } else {
+                    i - 1
+                }
+            }
+            None => 0,
+        };
+        self.state.select(Some(i));
     }
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let app = App::new();
+    let res = run_app(&mut terminal, app);
 
-    let mut table = SelectableTable::new();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    // Input
-    loop {
-        terminal.draw(|f| {
-            let rects = Layout::default()
-                .constraints([Constraint::Percentage(100)].as_ref())
-                .margin(5)
-                .split(f.size());
-
-            let selected_style = Style::default().add_modifier(Modifier::REVERSED);
-            let normal_style = Style::default().bg(Color::Blue);
-            let header_cells = ["Header1", "Header2", "Header3"]
-                .iter()
-                .map(|h| Cell::from(*h).style(Style::default().fg(Color::Red)));
-            let header = Row::new(header_cells)
-                .style(normal_style)
-                .height(1)
-                .bottom_margin(1);
-            let rows = table.items.iter().map(|item| {
-                let height = item
-                    .iter()
-                    .map(|content| content.chars().filter(|c| *c == '\n').count())
-                    .max()
-                    .unwrap_or(0)
-                    + 1;
-                let cells = item.iter().map(|c| Cell::from(*c));
-                Row::new(cells).height(height as u16).bottom_margin(1)
-            });
-            let t = Table::new(rows)
-                .header(header)
-                .block(Block::default().borders(Borders::ALL).title("Table"))
-                .highlight_style(selected_style)
-                .highlight_symbol(">> ")
-                .select(table.selected)
-                .widths(&[
-                    Constraint::Percentage(50),
-                    Constraint::Length(30),
-                    Constraint::Max(10),
-                ]);
-            f.render_widget(t, rects[0]);
-        })?;
-
-        if let Event::Input(key) = events.next()? {
-            match key {
-                Key::Char('q') => {
-                    break;
-                }
-                Key::Down => {
-                    table.next();
-                }
-                Key::Up => {
-                    table.previous();
-                }
-                _ => {}
-            }
-        };
+    if let Err(err) = res {
+        println!("{:?}", err)
     }
 
     Ok(())
 }
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, &mut app))?;
+
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('q') => return Ok(()),
+                KeyCode::Down => app.next(),
+                KeyCode::Up => app.previous(),
+                _ => {}
+            }
+        }
+    }
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+    let rects = Layout::default()
+        .constraints([Constraint::Percentage(100)].as_ref())
+        .margin(5)
+        .split(f.size());
+
+    let selected_style = Style::default().add_modifier(Modifier::REVERSED);
+    let normal_style = Style::default().bg(Color::Blue);
+    let header_cells = ["Header1", "Header2", "Header3"]
+        .iter()
+        .map(|h| Cell::from(*h).style(Style::default().fg(Color::Red)));
+    let header = Row::new(header_cells)
+        .style(normal_style)
+        .height(1)
+        .bottom_margin(1);
+    let rows = app.items.iter().map(|item| {
+        let height = item
+            .iter()
+            .map(|content| content.chars().filter(|c| *c == '\n').count())
+            .max()
+            .unwrap_or(0)
+            + 1;
+        let cells = item.iter().map(|c| Cell::from(*c));
+        Row::new(cells).height(height as u16).bottom_margin(1)
+    });
+    let t = Table::new(rows)
+        .header(header)
+        .block(Block::default().borders(Borders::ALL).title("Table"))
+        .highlight_style(selected_style)
+        .highlight_symbol(">> ")
+        .widths(&[
+            Constraint::Percentage(50),
+            Constraint::Length(30),
+            Constraint::Min(10),
+        ]);
+    f.render_stateful_widget(t, rects[0], &mut app.state);
+}

examples/tabs.rs

@@ -1,94 +1,124 @@
-#[allow(dead_code)]
-mod util;
-
-use crate::util::{
-    event::{Event, Events},
-    TabsState,
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     text::{Span, Spans},
     widgets::{Block, Borders, Tabs},
-    Terminal,
+    Frame, Terminal,
 };
 
 struct App<'a> {
-    tabs: TabsState<'a>,
+    pub titles: Vec<&'a str>,
+    pub index: usize,
+}
+
+impl<'a> App<'a> {
+    fn new() -> App<'a> {
+        App {
+            titles: vec!["Tab0", "Tab1", "Tab2", "Tab3"],
+            index: 0,
+        }
+    }
+
+    pub fn next(&mut self) {
+        self.index = (self.index + 1) % self.titles.len();
+    }
+
+    pub fn previous(&mut self) {
+        if self.index > 0 {
+            self.index -= 1;
+        } else {
+            self.index = self.titles.len() - 1;
+        }
+    }
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    let events = Events::new();
+    // create app and run it
+    let app = App::new();
+    let res = run_app(&mut terminal, app);
 
-    // App
-    let mut app = App {
-        tabs: TabsState::new(vec!["Tab0", "Tab1", "Tab2", "Tab3"]),
-    };
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
-    // Main loop
+    if let Err(err) = res {
+        println!("{:?}", err)
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
     loop {
-        terminal.draw(|f| {
-            let size = f.size();
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(5)
-                .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
-                .split(size);
+        terminal.draw(|f| ui(f, &app))?;
 
-            let block = Block::default().style(Style::default().bg(Color::White).fg(Color::Black));
-            f.render_widget(block, size);
-            let titles = app
-                .tabs
-                .titles
-                .iter()
-                .map(|t| {
-                    let (first, rest) = t.split_at(1);
-                    Spans::from(vec![
-                        Span::styled(first, Style::default().fg(Color::Yellow)),
-                        Span::styled(rest, Style::default().fg(Color::Green)),
-                    ])
-                })
-                .collect();
-            let tabs = Tabs::new(titles)
-                .block(Block::default().borders(Borders::ALL).title("Tabs"))
-                .select(app.tabs.index)
-                .style(Style::default().fg(Color::Cyan))
-                .highlight_style(
-                    Style::default()
-                        .add_modifier(Modifier::BOLD)
-                        .bg(Color::Black),
-                );
-            f.render_widget(tabs, chunks[0]);
-            let inner = match app.tabs.index {
-                0 => Block::default().title("Inner 0").borders(Borders::ALL),
-                1 => Block::default().title("Inner 1").borders(Borders::ALL),
-                2 => Block::default().title("Inner 2").borders(Borders::ALL),
-                3 => Block::default().title("Inner 3").borders(Borders::ALL),
-                _ => unreachable!(),
-            };
-            f.render_widget(inner, chunks[1]);
-        })?;
-
-        if let Event::Input(input) = events.next()? {
-            match input {
-                Key::Char('q') => {
-                    break;
-                }
-                Key::Right => app.tabs.next(),
-                Key::Left => app.tabs.previous(),
+        if let Event::Key(key) = event::read()? {
+            match key.code {
+                KeyCode::Char('q') => return Ok(()),
+                KeyCode::Right => app.next(),
+                KeyCode::Left => app.previous(),
                 _ => {}
             }
         }
     }
-    Ok(())
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let size = f.size();
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(5)
+        .constraints([Constraint::Length(3), Constraint::Min(0)].as_ref())
+        .split(size);
+
+    let block = Block::default().style(Style::default().bg(Color::White).fg(Color::Black));
+    f.render_widget(block, size);
+    let titles = app
+        .titles
+        .iter()
+        .map(|t| {
+            let (first, rest) = t.split_at(1);
+            Spans::from(vec![
+                Span::styled(first, Style::default().fg(Color::Yellow)),
+                Span::styled(rest, Style::default().fg(Color::Green)),
+            ])
+        })
+        .collect();
+    let tabs = Tabs::new(titles)
+        .block(Block::default().borders(Borders::ALL).title("Tabs"))
+        .select(app.index)
+        .style(Style::default().fg(Color::Cyan))
+        .highlight_style(
+            Style::default()
+                .add_modifier(Modifier::BOLD)
+                .bg(Color::Black),
+        );
+    f.render_widget(tabs, chunks[0]);
+    let inner = match app.index {
+        0 => Block::default().title("Inner 0").borders(Borders::ALL),
+        1 => Block::default().title("Inner 1").borders(Borders::ALL),
+        2 => Block::default().title("Inner 2").borders(Borders::ALL),
+        3 => Block::default().title("Inner 3").borders(Borders::ALL),
+        _ => unreachable!(),
+    };
+    f.render_widget(inner, chunks[1]);
 }

examples/termion_demo.rs

@@ -1,72 +0,0 @@
-mod demo;
-#[allow(dead_code)]
-mod util;
-
-use crate::{
-    demo::{ui, App},
-    util::event::{Config, Event, Events},
-};
-use argh::FromArgs;
-use std::{error::Error, io, time::Duration};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
-use tui::{backend::TermionBackend, Terminal};
-
-/// Termion demo
-#[derive(Debug, FromArgs)]
-struct Cli {
-    /// time in ms between two ticks.
-    #[argh(option, default = "250")]
-    tick_rate: u64,
-    /// whether unicode symbols are used to improve the overall look of the app
-    #[argh(option, default = "true")]
-    enhanced_graphics: bool,
-}
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let cli: Cli = argh::from_env();
-
-    let events = Events::with_config(Config {
-        tick_rate: Duration::from_millis(cli.tick_rate),
-        ..Config::default()
-    });
-
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    let mut app = App::new("Termion demo", cli.enhanced_graphics);
-    loop {
-        terminal.draw(|f| ui::draw(f, &mut app))?;
-
-        match events.next()? {
-            Event::Input(key) => match key {
-                Key::Char(c) => {
-                    app.on_key(c);
-                }
-                Key::Up => {
-                    app.on_up();
-                }
-                Key::Down => {
-                    app.on_down();
-                }
-                Key::Left => {
-                    app.on_left();
-                }
-                Key::Right => {
-                    app.on_right();
-                }
-                _ => {}
-            },
-            Event::Tick => {
-                app.on_tick();
-            }
-        }
-        if app.should_quit {
-            break;
-        }
-    }
-
-    Ok(())
-}

examples/user_input.rs

@@ -9,20 +9,19 @@
 ///   * Pressing Backspace erases a character
 ///   * Pressing Enter pushes the current input in the history of previous
 ///   messages
-
-#[allow(dead_code)]
-mod util;
-
-use crate::util::event::{Event, Events};
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
 use std::{error::Error, io};
-use termion::{event::Key, input::MouseTerminal, raw::IntoRawMode, screen::AlternateScreen};
 use tui::{
-    backend::TermionBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     text::{Span, Spans, Text},
     widgets::{Block, Borders, List, ListItem, Paragraph},
-    Terminal,
+    Frame, Terminal,
 };
 use unicode_width::UnicodeWidthStr;
 
@@ -52,130 +51,142 @@ impl Default for App {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    // Terminal initialization
-    let stdout = io::stdout().into_raw_mode()?;
-    let stdout = MouseTerminal::from(stdout);
-    let stdout = AlternateScreen::from(stdout);
-    let backend = TermionBackend::new(stdout);
+    // setup terminal
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
     let mut terminal = Terminal::new(backend)?;
 
-    // Setup event handlers
-    let mut events = Events::new();
+    // create app and run it
+    let app = App::default();
+    let res = run_app(&mut terminal, app);
 
-    // Create default app state
-    let mut app = App::default();
+    // restore terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
 
+    if let Err(err) = res {
+        println!("{:?}", err)
+    }
+
+    Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
     loop {
-        // Draw UI
-        terminal.draw(|f| {
-            let chunks = Layout::default()
-                .direction(Direction::Vertical)
-                .margin(2)
-                .constraints(
-                    [
-                        Constraint::Length(1),
-                        Constraint::Length(3),
-                        Constraint::Min(1),
-                    ]
-                    .as_ref(),
-                )
-                .split(f.size());
+        terminal.draw(|f| ui(f, &app))?;
 
-            let (msg, style) = match app.input_mode {
-                InputMode::Normal => (
-                    vec![
-                        Span::raw("Press "),
-                        Span::styled("q", Style::default().add_modifier(Modifier::BOLD)),
-                        Span::raw(" to exit, "),
-                        Span::styled("e", Style::default().add_modifier(Modifier::BOLD)),
-                        Span::raw(" to start editing."),
-                    ],
-                    Style::default().add_modifier(Modifier::RAPID_BLINK),
-                ),
-                InputMode::Editing => (
-                    vec![
-                        Span::raw("Press "),
-                        Span::styled("Esc", Style::default().add_modifier(Modifier::BOLD)),
-                        Span::raw(" to stop editing, "),
-                        Span::styled("Enter", Style::default().add_modifier(Modifier::BOLD)),
-                        Span::raw(" to record the message"),
-                    ],
-                    Style::default(),
-                ),
-            };
-            let mut text = Text::from(Spans::from(msg));
-            text.patch_style(style);
-            let help_message = Paragraph::new(text);
-            f.render_widget(help_message, chunks[0]);
-
-            let input = Paragraph::new(app.input.as_ref())
-                .style(match app.input_mode {
-                    InputMode::Normal => Style::default(),
-                    InputMode::Editing => Style::default().fg(Color::Yellow),
-                })
-                .block(Block::default().borders(Borders::ALL).title("Input"));
-            f.render_widget(input, chunks[1]);
+        if let Event::Key(key) = event::read()? {
             match app.input_mode {
-                InputMode::Normal =>
-                    // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
-                    {}
-
-                InputMode::Editing => {
-                    // Make the cursor visible and ask tui-rs to put it at the specified coordinates after rendering
-                    f.set_cursor(
-                        // Put cursor past the end of the input text
-                        chunks[1].x + app.input.width() as u16 + 1,
-                        // Move one line down, from the border to the input line
-                        chunks[1].y + 1,
-                    )
-                }
-            }
-
-            let messages: Vec<ListItem> = app
-                .messages
-                .iter()
-                .enumerate()
-                .map(|(i, m)| {
-                    let content = vec![Spans::from(Span::raw(format!("{}: {}", i, m)))];
-                    ListItem::new(content)
-                })
-                .collect();
-            let messages =
-                List::new(messages).block(Block::default().borders(Borders::ALL).title("Messages"));
-            f.render_widget(messages, chunks[2]);
-        })?;
-
-        // Handle input
-        if let Event::Input(input) = events.next()? {
-            match app.input_mode {
-                InputMode::Normal => match input {
-                    Key::Char('e') => {
+                InputMode::Normal => match key.code {
+                    KeyCode::Char('e') => {
                         app.input_mode = InputMode::Editing;
-                        events.disable_exit_key();
                     }
-                    Key::Char('q') => {
-                        break;
+                    KeyCode::Char('q') => {
+                        return Ok(());
                     }
                     _ => {}
                 },
-                InputMode::Editing => match input {
-                    Key::Char('\n') => {
+                InputMode::Editing => match key.code {
+                    KeyCode::Enter => {
                         app.messages.push(app.input.drain(..).collect());
                     }
-                    Key::Char(c) => {
+                    KeyCode::Char(c) => {
                         app.input.push(c);
                     }
-                    Key::Backspace => {
+                    KeyCode::Backspace => {
                         app.input.pop();
                     }
-                    Key::Esc => {
+                    KeyCode::Esc => {
                         app.input_mode = InputMode::Normal;
-                        events.enable_exit_key();
                     }
                     _ => {}
                 },
             }
         }
     }
-    Ok(())
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .margin(2)
+        .constraints(
+            [
+                Constraint::Length(1),
+                Constraint::Length(3),
+                Constraint::Min(1),
+            ]
+            .as_ref(),
+        )
+        .split(f.size());
+
+    let (msg, style) = match app.input_mode {
+        InputMode::Normal => (
+            vec![
+                Span::raw("Press "),
+                Span::styled("q", Style::default().add_modifier(Modifier::BOLD)),
+                Span::raw(" to exit, "),
+                Span::styled("e", Style::default().add_modifier(Modifier::BOLD)),
+                Span::raw(" to start editing."),
+            ],
+            Style::default().add_modifier(Modifier::RAPID_BLINK),
+        ),
+        InputMode::Editing => (
+            vec![
+                Span::raw("Press "),
+                Span::styled("Esc", Style::default().add_modifier(Modifier::BOLD)),
+                Span::raw(" to stop editing, "),
+                Span::styled("Enter", Style::default().add_modifier(Modifier::BOLD)),
+                Span::raw(" to record the message"),
+            ],
+            Style::default(),
+        ),
+    };
+    let mut text = Text::from(Spans::from(msg));
+    text.patch_style(style);
+    let help_message = Paragraph::new(text);
+    f.render_widget(help_message, chunks[0]);
+
+    let input = Paragraph::new(app.input.as_ref())
+        .style(match app.input_mode {
+            InputMode::Normal => Style::default(),
+            InputMode::Editing => Style::default().fg(Color::Yellow),
+        })
+        .block(Block::default().borders(Borders::ALL).title("Input"));
+    f.render_widget(input, chunks[1]);
+    match app.input_mode {
+        InputMode::Normal =>
+            // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
+            {}
+
+        InputMode::Editing => {
+            // Make the cursor visible and ask tui-rs to put it at the specified coordinates after rendering
+            f.set_cursor(
+                // Put cursor past the end of the input text
+                chunks[1].x + app.input.width() as u16 + 1,
+                // Move one line down, from the border to the input line
+                chunks[1].y + 1,
+            )
+        }
+    }
+
+    let messages: Vec<ListItem> = app
+        .messages
+        .iter()
+        .enumerate()
+        .map(|(i, m)| {
+            let content = vec![Spans::from(Span::raw(format!("{}: {}", i, m)))];
+            ListItem::new(content)
+        })
+        .collect();
+    let messages =
+        List::new(messages).block(Block::default().borders(Borders::ALL).title("Messages"));
+    f.render_widget(messages, chunks[2]);
 }

examples/util/event.rs

@@ -1,95 +0,0 @@
-use std::io;
-use std::sync::mpsc;
-use std::sync::{
-    atomic::{AtomicBool, Ordering},
-    Arc,
-};
-use std::thread;
-use std::time::Duration;
-
-use termion::event::Key;
-use termion::input::TermRead;
-
-pub enum Event<I> {
-    Input(I),
-    Tick,
-}
-
-/// A small event handler that wrap termion input and tick events. Each event
-/// type is handled in its own thread and returned to a common `Receiver`
-pub struct Events {
-    rx: mpsc::Receiver<Event<Key>>,
-    input_handle: thread::JoinHandle<()>,
-    ignore_exit_key: Arc<AtomicBool>,
-    tick_handle: thread::JoinHandle<()>,
-}
-
-#[derive(Debug, Clone, Copy)]
-pub struct Config {
-    pub exit_key: Key,
-    pub tick_rate: Duration,
-}
-
-impl Default for Config {
-    fn default() -> Config {
-        Config {
-            exit_key: Key::Char('q'),
-            tick_rate: Duration::from_millis(250),
-        }
-    }
-}
-
-impl Events {
-    pub fn new() -> Events {
-        Events::with_config(Config::default())
-    }
-
-    pub fn with_config(config: Config) -> Events {
-        let (tx, rx) = mpsc::channel();
-        let ignore_exit_key = Arc::new(AtomicBool::new(false));
-        let input_handle = {
-            let tx = tx.clone();
-            let ignore_exit_key = ignore_exit_key.clone();
-            thread::spawn(move || {
-                let stdin = io::stdin();
-                for evt in stdin.keys() {
-                    if let Ok(key) = evt {
-                        if let Err(err) = tx.send(Event::Input(key)) {
-                            eprintln!("{}", err);
-                            return;
-                        }
-                        if !ignore_exit_key.load(Ordering::Relaxed) && key == config.exit_key {
-                            return;
-                        }
-                    }
-                }
-            })
-        };
-        let tick_handle = {
-            thread::spawn(move || loop {
-                if tx.send(Event::Tick).is_err() {
-                    break;
-                }
-                thread::sleep(config.tick_rate);
-            })
-        };
-        Events {
-            rx,
-            ignore_exit_key,
-            input_handle,
-            tick_handle,
-        }
-    }
-
-    pub fn next(&self) -> Result<Event<Key>, mpsc::RecvError> {
-        self.rx.recv()
-    }
-
-    pub fn disable_exit_key(&mut self) {
-        self.ignore_exit_key.store(true, Ordering::Relaxed);
-    }
-
-    pub fn enable_exit_key(&mut self) {
-        self.ignore_exit_key.store(false, Ordering::Relaxed);
-    }
-}

examples/util/mod.rs

@@ -1,128 +0,0 @@
-#[cfg(feature = "termion")]
-pub mod event;
-
-use rand::distributions::{Distribution, Uniform};
-use rand::rngs::ThreadRng;
-
-#[derive(Clone)]
-pub struct RandomSignal {
-    distribution: Uniform<u64>,
-    rng: ThreadRng,
-}
-
-impl RandomSignal {
-    pub fn new(lower: u64, upper: u64) -> RandomSignal {
-        RandomSignal {
-            distribution: Uniform::new(lower, upper),
-            rng: rand::thread_rng(),
-        }
-    }
-}
-
-impl Iterator for RandomSignal {
-    type Item = u64;
-    fn next(&mut self) -> Option<u64> {
-        Some(self.distribution.sample(&mut self.rng))
-    }
-}
-
-#[derive(Clone)]
-pub struct SinSignal {
-    x: f64,
-    interval: f64,
-    period: f64,
-    scale: f64,
-}
-
-impl SinSignal {
-    pub fn new(interval: f64, period: f64, scale: f64) -> SinSignal {
-        SinSignal {
-            x: 0.0,
-            interval,
-            period,
-            scale,
-        }
-    }
-}
-
-impl Iterator for SinSignal {
-    type Item = (f64, f64);
-    fn next(&mut self) -> Option<Self::Item> {
-        let point = (self.x, (self.x * 1.0 / self.period).sin() * self.scale);
-        self.x += self.interval;
-        Some(point)
-    }
-}
-
-pub struct TabsState<'a> {
-    pub titles: Vec<&'a str>,
-    pub index: usize,
-}
-
-impl<'a> TabsState<'a> {
-    pub fn new(titles: Vec<&'a str>) -> TabsState {
-        TabsState { titles, index: 0 }
-    }
-    pub fn next(&mut self) {
-        self.index = (self.index + 1) % self.titles.len();
-    }
-
-    pub fn previous(&mut self) {
-        if self.index > 0 {
-            self.index -= 1;
-        } else {
-            self.index = self.titles.len() - 1;
-        }
-    }
-}
-
-pub struct SelectableList<T> {
-    pub selected: Option<usize>,
-    pub items: Vec<T>,
-}
-
-impl<T> SelectableList<T> {
-    pub fn new() -> SelectableList<T> {
-        Self {
-            selected: None,
-            items: Vec::new(),
-        }
-    }
-
-    pub fn with_items(items: Vec<T>) -> SelectableList<T> {
-        Self {
-            selected: None,
-            items,
-        }
-    }
-
-    pub fn next(&mut self) {
-        self.selected = self
-            .selected
-            .map(|i| {
-                if i < self.items.len().saturating_sub(1) {
-                    i + 1
-                } else {
-                    0
-                }
-            })
-            .or(Some(0));
-    }
-
-    pub fn previous(&mut self) {
-        self.selected = self
-            .selected
-            .map(|i| {
-                if i > 0 {
-                    i - 1
-                } else {
-                    self.items.len().saturating_sub(1)
-                }
-            })
-            .or(Some(0));
-    }
-
-    pub fn unselect(&mut self) {
-        self.selected = None;
-    }
-}

src/backend/curses.rs

@@ -1,280 +0,0 @@
-use std::io;
-
-use crate::backend::Backend;
-use crate::buffer::Cell;
-use crate::layout::Rect;
-use crate::style::{Color, Modifier};
-use crate::symbols::{bar, block};
-#[cfg(unix)]
-use crate::symbols::{line, DOT};
-#[cfg(unix)]
-use pancurses::{chtype, ToChtype};
-use unicode_segmentation::UnicodeSegmentation;
-
-pub struct CursesBackend {
-    curses: easycurses::EasyCurses,
-}
-
-impl CursesBackend {
-    pub fn new() -> Option<CursesBackend> {
-        let curses = easycurses::EasyCurses::initialize_system()?;
-        Some(CursesBackend { curses })
-    }
-
-    pub fn with_curses(curses: easycurses::EasyCurses) -> CursesBackend {
-        CursesBackend { curses }
-    }
-
-    pub fn get_curses(&self) -> &easycurses::EasyCurses {
-        &self.curses
-    }
-
-    pub fn get_curses_mut(&mut self) -> &mut easycurses::EasyCurses {
-        &mut self.curses
-    }
-}
-
-impl Backend for CursesBackend {
-    fn draw<'a, I>(&mut self, content: I) -> io::Result<()>
-    where
-        I: Iterator<Item = (u16, u16, &'a Cell)>,
-    {
-        let mut last_col = 0;
-        let mut last_row = 0;
-        let mut fg = Color::Reset;
-        let mut bg = Color::Reset;
-        let mut modifier = Modifier::empty();
-        let mut curses_style = CursesStyle {
-            fg: easycurses::Color::White,
-            bg: easycurses::Color::Black,
-        };
-        let mut update_color = false;
-        for (col, row, cell) in content {
-            if row != last_row || col != last_col + 1 {
-                self.curses.move_rc(i32::from(row), i32::from(col));
-            }
-            last_col = col;
-            last_row = row;
-            if cell.modifier != modifier {
-                apply_modifier_diff(&mut self.curses.win, modifier, cell.modifier);
-                modifier = cell.modifier;
-            };
-            if cell.fg != fg {
-                update_color = true;
-                if let Some(ccolor) = cell.fg.into() {
-                    fg = cell.fg;
-                    curses_style.fg = ccolor;
-                } else {
-                    fg = Color::White;
-                    curses_style.fg = easycurses::Color::White;
-                }
-            };
-            if cell.bg != bg {
-                update_color = true;
-                if let Some(ccolor) = cell.bg.into() {
-                    bg = cell.bg;
-                    curses_style.bg = ccolor;
-                } else {
-                    bg = Color::Black;
-                    curses_style.bg = easycurses::Color::Black;
-                }
-            };
-            if update_color {
-                self.curses
-                    .set_color_pair(easycurses::ColorPair::new(curses_style.fg, curses_style.bg));
-            };
-            update_color = false;
-            draw(&mut self.curses, cell.symbol.as_str());
-        }
-        self.curses.win.attrset(pancurses::Attribute::Normal);
-        self.curses.set_color_pair(easycurses::ColorPair::new(
-            easycurses::Color::White,
-            easycurses::Color::Black,
-        ));
-        Ok(())
-    }
-    fn hide_cursor(&mut self) -> io::Result<()> {
-        self.curses
-            .set_cursor_visibility(easycurses::CursorVisibility::Invisible);
-        Ok(())
-    }
-    fn show_cursor(&mut self) -> io::Result<()> {
-        self.curses
-            .set_cursor_visibility(easycurses::CursorVisibility::Visible);
-        Ok(())
-    }
-    fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
-        let (y, x) = self.curses.get_cursor_rc();
-        Ok((x as u16, y as u16))
-    }
-    fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
-        self.curses.move_rc(i32::from(y), i32::from(x));
-        Ok(())
-    }
-    fn clear(&mut self) -> io::Result<()> {
-        self.curses.clear();
-        // self.curses.refresh();
-        Ok(())
-    }
-    fn size(&self) -> Result<Rect, io::Error> {
-        let (nrows, ncols) = self.curses.get_row_col_count();
-        Ok(Rect::new(0, 0, ncols as u16, nrows as u16))
-    }
-    fn flush(&mut self) -> io::Result<()> {
-        self.curses.refresh();
-        Ok(())
-    }
-}
-
-struct CursesStyle {
-    fg: easycurses::Color,
-    bg: easycurses::Color,
-}
-
-#[cfg(unix)]
-/// Deals with lack of unicode support for ncurses on unix
-fn draw(curses: &mut easycurses::EasyCurses, symbol: &str) {
-    for grapheme in symbol.graphemes(true) {
-        let ch = match grapheme {
-            line::TOP_RIGHT => pancurses::ACS_URCORNER(),
-            line::VERTICAL => pancurses::ACS_VLINE(),
-            line::HORIZONTAL => pancurses::ACS_HLINE(),
-            line::TOP_LEFT => pancurses::ACS_ULCORNER(),
-            line::BOTTOM_RIGHT => pancurses::ACS_LRCORNER(),
-            line::BOTTOM_LEFT => pancurses::ACS_LLCORNER(),
-            line::VERTICAL_LEFT => pancurses::ACS_RTEE(),
-            line::VERTICAL_RIGHT => pancurses::ACS_LTEE(),
-            line::HORIZONTAL_DOWN => pancurses::ACS_TTEE(),
-            line::HORIZONTAL_UP => pancurses::ACS_BTEE(),
-            block::FULL => pancurses::ACS_BLOCK(),
-            block::SEVEN_EIGHTHS => pancurses::ACS_BLOCK(),
-            block::THREE_QUARTERS => pancurses::ACS_BLOCK(),
-            block::FIVE_EIGHTHS => pancurses::ACS_BLOCK(),
-            block::HALF => pancurses::ACS_BLOCK(),
-            block::THREE_EIGHTHS => ' ' as chtype,
-            block::ONE_QUARTER => ' ' as chtype,
-            block::ONE_EIGHTH => ' ' as chtype,
-            bar::SEVEN_EIGHTHS => pancurses::ACS_BLOCK(),
-            bar::THREE_QUARTERS => pancurses::ACS_BLOCK(),
-            bar::FIVE_EIGHTHS => pancurses::ACS_BLOCK(),
-            bar::HALF => pancurses::ACS_BLOCK(),
-            bar::THREE_EIGHTHS => pancurses::ACS_S9(),
-            bar::ONE_QUARTER => pancurses::ACS_S9(),
-            bar::ONE_EIGHTH => pancurses::ACS_S9(),
-            DOT => pancurses::ACS_BULLET(),
-            unicode_char => {
-                if unicode_char.is_ascii() {
-                    let mut chars = unicode_char.chars();
-                    if let Some(ch) = chars.next() {
-                        ch.to_chtype()
-                    } else {
-                        pancurses::ACS_BLOCK()
-                    }
-                } else {
-                    pancurses::ACS_BLOCK()
-                }
-            }
-        };
-        curses.win.addch(ch);
-    }
-}
-
-#[cfg(windows)]
-fn draw(curses: &mut easycurses::EasyCurses, symbol: &str) {
-    for grapheme in symbol.graphemes(true) {
-        let ch = match grapheme {
-            block::SEVEN_EIGHTHS => block::FULL,
-            block::THREE_QUARTERS => block::FULL,
-            block::FIVE_EIGHTHS => block::HALF,
-            block::THREE_EIGHTHS => block::HALF,
-            block::ONE_QUARTER => block::HALF,
-            block::ONE_EIGHTH => " ",
-            bar::SEVEN_EIGHTHS => bar::FULL,
-            bar::THREE_QUARTERS => bar::FULL,
-            bar::FIVE_EIGHTHS => bar::HALF,
-            bar::THREE_EIGHTHS => bar::HALF,
-            bar::ONE_QUARTER => bar::HALF,
-            bar::ONE_EIGHTH => " ",
-            ch => ch,
-        };
-        // curses.win.addch(ch);
-        curses.print(ch);
-    }
-}
-
-impl From<Color> for Option<easycurses::Color> {
-    fn from(color: Color) -> Option<easycurses::Color> {
-        match color {
-            Color::Reset => None,
-            Color::Black => Some(easycurses::Color::Black),
-            Color::Red | Color::LightRed => Some(easycurses::Color::Red),
-            Color::Green | Color::LightGreen => Some(easycurses::Color::Green),
-            Color::Yellow | Color::LightYellow => Some(easycurses::Color::Yellow),
-            Color::Magenta | Color::LightMagenta => Some(easycurses::Color::Magenta),
-            Color::Cyan | Color::LightCyan => Some(easycurses::Color::Cyan),
-            Color::White | Color::Gray | Color::DarkGray => Some(easycurses::Color::White),
-            Color::Blue | Color::LightBlue => Some(easycurses::Color::Blue),
-            Color::Indexed(_) => None,
-            Color::Rgb(_, _, _) => None,
-        }
-    }
-}
-
-fn apply_modifier_diff(win: &mut pancurses::Window, from: Modifier, to: Modifier) {
-    remove_modifier(win, from - to);
-    add_modifier(win, to - from);
-}
-
-fn remove_modifier(win: &mut pancurses::Window, remove: Modifier) {
-    if remove.contains(Modifier::BOLD) {
-        win.attroff(pancurses::Attribute::Bold);
-    }
-    if remove.contains(Modifier::DIM) {
-        win.attroff(pancurses::Attribute::Dim);
-    }
-    if remove.contains(Modifier::ITALIC) {
-        win.attroff(pancurses::Attribute::Italic);
-    }
-    if remove.contains(Modifier::UNDERLINED) {
-        win.attroff(pancurses::Attribute::Underline);
-    }
-    if remove.contains(Modifier::SLOW_BLINK) || remove.contains(Modifier::RAPID_BLINK) {
-        win.attroff(pancurses::Attribute::Blink);
-    }
-    if remove.contains(Modifier::REVERSED) {
-        win.attroff(pancurses::Attribute::Reverse);
-    }
-    if remove.contains(Modifier::HIDDEN) {
-        win.attroff(pancurses::Attribute::Invisible);
-    }
-    if remove.contains(Modifier::CROSSED_OUT) {
-        win.attroff(pancurses::Attribute::Strikeout);
-    }
-}
-
-fn add_modifier(win: &mut pancurses::Window, add: Modifier) {
-    if add.contains(Modifier::BOLD) {
-        win.attron(pancurses::Attribute::Bold);
-    }
-    if add.contains(Modifier::DIM) {
-        win.attron(pancurses::Attribute::Dim);
-    }
-    if add.contains(Modifier::ITALIC) {
-        win.attron(pancurses::Attribute::Italic);
-    }
-    if add.contains(Modifier::UNDERLINED) {
-        win.attron(pancurses::Attribute::Underline);
-    }
-    if add.contains(Modifier::SLOW_BLINK) || add.contains(Modifier::RAPID_BLINK) {
-        win.attron(pancurses::Attribute::Blink);
-    }
-    if add.contains(Modifier::REVERSED) {
-        win.attron(pancurses::Attribute::Reverse);
-    }
-    if add.contains(Modifier::HIDDEN) {
-        win.attron(pancurses::Attribute::Invisible);
-    }
-    if add.contains(Modifier::CROSSED_OUT) {
-        win.attron(pancurses::Attribute::Strikeout);
-    }
-}

src/backend/mod.rs

@@ -3,11 +3,6 @@ use std::io;
 use crate::buffer::Cell;
 use crate::layout::Rect;
 
-#[cfg(feature = "rustbox")]
-mod rustbox;
-#[cfg(feature = "rustbox")]
-pub use self::rustbox::RustboxBackend;
-
 #[cfg(feature = "termion")]
 mod termion;
 #[cfg(feature = "termion")]
@@ -18,11 +13,6 @@ mod crossterm;
 #[cfg(feature = "crossterm")]
 pub use self::crossterm::CrosstermBackend;
 
-#[cfg(feature = "curses")]
-mod curses;
-#[cfg(feature = "curses")]
-pub use self::curses::CursesBackend;
-
 mod test;
 pub use self::test::TestBackend;
 

src/backend/rustbox.rs

@@ -1,123 +0,0 @@
-use crate::{
-    backend::Backend,
-    buffer::Cell,
-    layout::Rect,
-    style::{Color, Modifier},
-};
-use std::io;
-
-pub struct RustboxBackend {
-    rustbox: rustbox::RustBox,
-}
-
-impl RustboxBackend {
-    pub fn new() -> Result<RustboxBackend, rustbox::InitError> {
-        let rustbox = rustbox::RustBox::init(Default::default())?;
-        Ok(RustboxBackend { rustbox })
-    }
-
-    pub fn with_rustbox(instance: rustbox::RustBox) -> RustboxBackend {
-        RustboxBackend { rustbox: instance }
-    }
-
-    pub fn rustbox(&self) -> &rustbox::RustBox {
-        &self.rustbox
-    }
-}
-
-impl Backend for RustboxBackend {
-    fn draw<'a, I>(&mut self, content: I) -> Result<(), io::Error>
-    where
-        I: Iterator<Item = (u16, u16, &'a Cell)>,
-    {
-        for (x, y, cell) in content {
-            self.rustbox.print(
-                x as usize,
-                y as usize,
-                cell.modifier.into(),
-                cell.fg.into(),
-                cell.bg.into(),
-                &cell.symbol,
-            );
-        }
-        Ok(())
-    }
-    fn hide_cursor(&mut self) -> Result<(), io::Error> {
-        Ok(())
-    }
-    fn show_cursor(&mut self) -> Result<(), io::Error> {
-        Ok(())
-    }
-    fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
-        Err(io::Error::from(io::ErrorKind::Other))
-    }
-    fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
-        self.rustbox.set_cursor(x as isize, y as isize);
-        Ok(())
-    }
-    fn clear(&mut self) -> Result<(), io::Error> {
-        self.rustbox.clear();
-        Ok(())
-    }
-    fn size(&self) -> Result<Rect, io::Error> {
-        let term_width = self.rustbox.width();
-        let term_height = self.rustbox.height();
-        let max = u16::max_value();
-        Ok(Rect::new(
-            0,
-            0,
-            if term_width > usize::from(max) {
-                max
-            } else {
-                term_width as u16
-            },
-            if term_height > usize::from(max) {
-                max
-            } else {
-                term_height as u16
-            },
-        ))
-    }
-    fn flush(&mut self) -> Result<(), io::Error> {
-        self.rustbox.present();
-        Ok(())
-    }
-}
-
-fn rgb_to_byte(r: u8, g: u8, b: u8) -> u16 {
-    u16::from((r & 0xC0) + ((g & 0xE0) >> 2) + ((b & 0xE0) >> 5))
-}
-
-impl Into<rustbox::Color> for Color {
-    fn into(self) -> rustbox::Color {
-        match self {
-            Color::Reset => rustbox::Color::Default,
-            Color::Black | Color::Gray | Color::DarkGray => rustbox::Color::Black,
-            Color::Red | Color::LightRed => rustbox::Color::Red,
-            Color::Green | Color::LightGreen => rustbox::Color::Green,
-            Color::Yellow | Color::LightYellow => rustbox::Color::Yellow,
-            Color::Magenta | Color::LightMagenta => rustbox::Color::Magenta,
-            Color::Cyan | Color::LightCyan => rustbox::Color::Cyan,
-            Color::White => rustbox::Color::White,
-            Color::Blue | Color::LightBlue => rustbox::Color::Blue,
-            Color::Indexed(i) => rustbox::Color::Byte(u16::from(i)),
-            Color::Rgb(r, g, b) => rustbox::Color::Byte(rgb_to_byte(r, g, b)),
-        }
-    }
-}
-
-impl Into<rustbox::Style> for Modifier {
-    fn into(self) -> rustbox::Style {
-        let mut result = rustbox::Style::empty();
-        if self.contains(Modifier::BOLD) {
-            result.insert(rustbox::RB_BOLD);
-        }
-        if self.contains(Modifier::UNDERLINED) {
-            result.insert(rustbox::RB_UNDERLINE);
-        }
-        if self.contains(Modifier::REVERSED) {
-            result.insert(rustbox::RB_REVERSE);
-        }
-        result
-    }
-}

src/backend/test.rs

@@ -101,7 +101,7 @@ impl TestBackend {
             .collect::<Vec<String>>()
             .join("\n");
         debug_info.push_str(&nice_diff);
-        panic!(debug_info);
+        panic!("{}", debug_info);
     }
 }
 
@@ -137,6 +137,7 @@ impl Backend for TestBackend {
     }
 
     fn clear(&mut self) -> Result<(), io::Error> {
+        self.buffer.reset();
         Ok(())
     }
 

src/buffer.rs

@@ -105,7 +105,7 @@ impl Default for Cell {
 /// buf.get_mut(5, 0).set_char('x');
 /// assert_eq!(buf.get(5, 0).symbol, "x");
 /// ```
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Default)]
 pub struct Buffer {
     /// The area represented by this buffer
     pub area: Rect,
@@ -114,15 +114,6 @@ pub struct Buffer {
     pub content: Vec<Cell>,
 }
 
-impl Default for Buffer {
-    fn default() -> Buffer {
-        Buffer {
-            area: Default::default(),
-            content: Vec::new(),
-        }
-    }
-}
-
 impl Buffer {
     /// Returns a Buffer with all cells set to the default one
     pub fn empty(area: Rect) -> Buffer {

src/layout.rs

@@ -63,6 +63,9 @@ pub struct Layout {
     direction: Direction,
     margin: Margin,
     constraints: Vec<Constraint>,
+    /// Whether the last chunk of the computed layout should be expanded to fill the available
+    /// space.
+    expand_to_fill: bool,
 }
 
 thread_local! {
@@ -78,6 +81,7 @@ impl Default for Layout {
                 vertical: 0,
             },
             constraints: Vec::new(),
+            expand_to_fill: true,
         }
     }
 }
@@ -114,6 +118,11 @@ impl Layout {
         self
     }
 
+    pub(crate) fn expand_to_fill(mut self, expand_to_fill: bool) -> Layout {
+        self.expand_to_fill = expand_to_fill;
+        self
+    }
+
     /// Wrapper function around the cassowary-rs solver to be able to split a given
     /// area into smaller ones based on the preferred widths or heights and the direction.
     ///
@@ -222,11 +231,13 @@ fn split(area: Rect, layout: &Layout) -> Vec<Rect> {
             Direction::Vertical => first.top() | EQ(REQUIRED) | f64::from(dest_area.top()),
         });
     }
-    if let Some(last) = elements.last() {
-        ccs.push(match layout.direction {
-            Direction::Horizontal => last.right() | EQ(REQUIRED) | f64::from(dest_area.right()),
-            Direction::Vertical => last.bottom() | EQ(REQUIRED) | f64::from(dest_area.bottom()),
-        });
+    if layout.expand_to_fill {
+        if let Some(last) = elements.last() {
+            ccs.push(match layout.direction {
+                Direction::Horizontal => last.right() | EQ(REQUIRED) | f64::from(dest_area.right()),
+                Direction::Vertical => last.bottom() | EQ(REQUIRED) | f64::from(dest_area.bottom()),
+            });
+        }
     }
     match layout.direction {
         Direction::Horizontal => {
@@ -299,14 +310,16 @@ fn split(area: Rect, layout: &Layout) -> Vec<Rect> {
         }
     }
 
-    // Fix imprecision by extending the last item a bit if necessary
-    if let Some(last) = results.last_mut() {
-        match layout.direction {
-            Direction::Vertical => {
-                last.height = dest_area.bottom() - last.y;
-            }
-            Direction::Horizontal => {
-                last.width = dest_area.right() - last.x;
+    if layout.expand_to_fill {
+        // Fix imprecision by extending the last item a bit if necessary
+        if let Some(last) = results.last_mut() {
+            match layout.direction {
+                Direction::Vertical => {
+                    last.height = dest_area.bottom() - last.y;
+                }
+                Direction::Horizontal => {
+                    last.width = dest_area.right() - last.x;
+                }
             }
         }
     }
@@ -350,7 +363,7 @@ impl Element {
 
 /// A simple rectangle used in the computation of the layout and to give widgets an hint about the
 /// area they are supposed to render to.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default)]
 pub struct Rect {
     pub x: u16,
     pub y: u16,
@@ -358,17 +371,6 @@ pub struct Rect {
     pub height: u16,
 }
 
-impl Default for Rect {
-    fn default() -> Rect {
-        Rect {
-            x: 0,
-            y: 0,
-            width: 0,
-            height: 0,
-        }
-    }
-}
-
 impl Rect {
     /// Creates a new rect, with width and height limited to keep the area under max u16.
     /// If clipped, aspect ratio will be preserved.

src/lib.rs

@@ -9,18 +9,19 @@
 //!
 //! ```toml
 //! [dependencies]
-//! tui = "0.14"
-//! termion = "1.5"
+//! tui = "0.18"
+//! crossterm = "0.23"
 //! ```
 //!
-//! The crate is using the `termion` backend by default but if for example you want your
-//! application to work on Windows, you might want to use the `crossterm` backend instead. This can
-//! be done by changing your dependencies specification to the following:
+//! The crate is using the `crossterm` backend by default that works on most platforms. But if for
+//! example you want to use the `termion` backend instead. This can be done by changing your
+//! dependencies specification to the following:
 //!
 //! ```toml
 //! [dependencies]
-//! crossterm = "0.19"
-//! tui = { version = "0.14", default-features = false, features = ['crossterm'] }
+//! termion = "1.5"
+//! tui = { version = "0.18", default-features = false, features = ['termion'] }
+//!
 //! ```
 //!
 //! The same logic applies for all other available backends.
@@ -33,29 +34,27 @@
 //!
 //! ```rust,no_run
 //! use std::io;
-//! use tui::Terminal;
-//! use tui::backend::TermionBackend;
-//! use termion::raw::IntoRawMode;
+//! use tui::{backend::CrosstermBackend, Terminal};
 //!
 //! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout().into_raw_mode()?;
-//!     let backend = TermionBackend::new(stdout);
+//!     let stdout = io::stdout();
+//!     let backend = CrosstermBackend::new(stdout);
 //!     let mut terminal = Terminal::new(backend)?;
 //!     Ok(())
 //! }
 //! ```
 //!
-//! If you had previously chosen `crossterm` as a backend, the terminal can be created in a similar
+//! If you had previously chosen `termion` as a backend, the terminal can be created in a similar
 //! way:
 //!
 //! ```rust,ignore
 //! use std::io;
-//! use tui::Terminal;
-//! use tui::backend::CrosstermBackend;
+//! use tui::{backend::TermionBackend, Terminal};
+//! use termion::raw::IntoRawMode;
 //!
 //! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout();
-//!     let backend = CrosstermBackend::new(stdout);
+//!     let stdout = io::stdout().into_raw_mode()?;
+//!     let backend = TermionBackend::new(stdout);
 //!     let mut terminal = Terminal::new(backend)?;
 //!     Ok(())
 //! }
@@ -71,23 +70,33 @@
 //! implement your own.
 //!
 //! Each widget follows a builder pattern API providing a default configuration along with methods
-//! to customize them. The widget is then rendered using the [`Frame::render_widget`] which take
-//! your widget instance an area to draw to.
+//! to customize them. The widget is then rendered using [`Frame::render_widget`] which takes
+//! your widget instance and an area to draw to.
 //!
 //! The following example renders a block of the size of the terminal:
 //!
 //! ```rust,no_run
-//! use std::io;
-//! use termion::raw::IntoRawMode;
-//! use tui::Terminal;
-//! use tui::backend::TermionBackend;
-//! use tui::widgets::{Widget, Block, Borders};
-//! use tui::layout::{Layout, Constraint, Direction};
+//! use std::{io, thread, time::Duration};
+//! use tui::{
+//!     backend::CrosstermBackend,
+//!     widgets::{Widget, Block, Borders},
+//!     layout::{Layout, Constraint, Direction},
+//!     Terminal
+//! };
+//! use crossterm::{
+//!     event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+//!     execute,
+//!     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+//! };
 //!
 //! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout().into_raw_mode()?;
-//!     let backend = TermionBackend::new(stdout);
+//!     // setup terminal
+//!     enable_raw_mode()?;
+//!     let mut stdout = io::stdout();
+//!     execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+//!     let backend = CrosstermBackend::new(stdout);
 //!     let mut terminal = Terminal::new(backend)?;
+//!
 //!     terminal.draw(|f| {
 //!         let size = f.size();
 //!         let block = Block::default()
@@ -95,6 +104,18 @@
 //!             .borders(Borders::ALL);
 //!         f.render_widget(block, size);
 //!     })?;
+//!
+//!     thread::sleep(Duration::from_millis(5000));
+//!
+//!     // restore terminal
+//!     disable_raw_mode()?;
+//!     execute!(
+//!         terminal.backend_mut(),
+//!         LeaveAlternateScreen,
+//!         DisableMouseCapture
+//!     )?;
+//!     terminal.show_cursor()?;
+//!
 //!     Ok(())
 //! }
 //! ```
@@ -106,39 +127,32 @@
 //! full customization. And `Layout` is no exception:
 //!
 //! ```rust,no_run
-//! use std::io;
-//! use termion::raw::IntoRawMode;
-//! use tui::Terminal;
-//! use tui::backend::TermionBackend;
-//! use tui::widgets::{Widget, Block, Borders};
-//! use tui::layout::{Layout, Constraint, Direction};
-//!
-//! fn main() -> Result<(), io::Error> {
-//!     let stdout = io::stdout().into_raw_mode()?;
-//!     let backend = TermionBackend::new(stdout);
-//!     let mut terminal = Terminal::new(backend)?;
-//!     terminal.draw(|f| {
-//!         let chunks = Layout::default()
-//!             .direction(Direction::Vertical)
-//!             .margin(1)
-//!             .constraints(
-//!                 [
-//!                     Constraint::Percentage(10),
-//!                     Constraint::Percentage(80),
-//!                     Constraint::Percentage(10)
-//!                 ].as_ref()
-//!             )
-//!             .split(f.size());
-//!         let block = Block::default()
-//!              .title("Block")
-//!              .borders(Borders::ALL);
-//!         f.render_widget(block, chunks[0]);
-//!         let block = Block::default()
-//!              .title("Block 2")
-//!              .borders(Borders::ALL);
-//!         f.render_widget(block, chunks[1]);
-//!     })?;
-//!     Ok(())
+//! use tui::{
+//!     backend::Backend,
+//!     layout::{Constraint, Direction, Layout},
+//!     widgets::{Block, Borders},
+//!     Frame,
+//! };
+//! fn ui<B: Backend>(f: &mut Frame<B>) {
+//!    let chunks = Layout::default()
+//!         .direction(Direction::Vertical)
+//!         .margin(1)
+//!         .constraints(
+//!             [
+//!                 Constraint::Percentage(10),
+//!                 Constraint::Percentage(80),
+//!                 Constraint::Percentage(10)
+//!             ].as_ref()
+//!         )
+//!         .split(f.size());
+//!     let block = Block::default()
+//!          .title("Block")
+//!          .borders(Borders::ALL);
+//!     f.render_widget(block, chunks[0]);
+//!     let block = Block::default()
+//!          .title("Block 2")
+//!          .borders(Borders::ALL);
+//!     f.render_widget(block, chunks[1]);
 //! }
 //! ```
 //!
@@ -156,4 +170,4 @@ pub mod terminal;
 pub mod text;
 pub mod widgets;
 
-pub use self::terminal::{Frame, RenderArgs, Terminal, TerminalOptions, Viewport};
+pub use self::terminal::{Frame, Terminal, TerminalOptions, Viewport};

src/terminal.rs

@@ -2,9 +2,9 @@ use crate::{
     backend::Backend,
     buffer::Buffer,
     layout::Rect,
-    widgets::{RenderContext, Widget},
+    widgets::{StatefulWidget, Widget},
 };
-use std::{any::Any, collections::HashMap, hash::Hash, io, panic::Location};
+use std::io;
 
 #[derive(Debug, Clone, PartialEq)]
 /// UNSTABLE
@@ -30,46 +30,6 @@ impl Viewport {
     }
 }
 
-#[derive(Clone, Copy, Debug)]
-pub(crate) struct CallLocation(&'static Location<'static>);
-
-impl CallLocation {
-    fn as_ptr(&self) -> *const Location<'static> {
-        self.0
-    }
-}
-
-impl Hash for CallLocation {
-    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
-        self.as_ptr().hash(state)
-    }
-}
-
-impl PartialEq for CallLocation {
-    fn eq(&self, other: &Self) -> bool {
-        self.as_ptr() == other.as_ptr()
-    }
-}
-
-impl Eq for CallLocation {}
-
-/// StateEntry is used to link a [`Frame::render_widget`] to [`Widget::State`].
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-struct StateKey {
-    /// Location of the call to [`Frame::render_widget`].
-    call_location: CallLocation,
-    /// Optional id that can be used to have multiple widgets state at the same call location.
-    id: Option<String>,
-}
-
-/// StateEntry holds the state of a [`Widget`].
-struct StateEntry {
-    /// State of a [`Widget`].
-    state: Box<dyn Any>,
-    /// Index of the frame where the state was used for the last time.
-    frame_index: usize,
-}
-
 #[derive(Debug, Clone, PartialEq)]
 /// Options to pass to [`Terminal::with_options`]
 pub struct TerminalOptions {
@@ -78,6 +38,7 @@ pub struct TerminalOptions {
 }
 
 /// Interface to the terminal backed by Termion
+#[derive(Debug)]
 pub struct Terminal<B>
 where
     B: Backend,
@@ -92,11 +53,6 @@ where
     hidden_cursor: bool,
     /// Viewport
     viewport: Viewport,
-    /// State of the widgets rendered in the previous frame.
-    widget_states: HashMap<StateKey, StateEntry>,
-    /// Index of the current frame. Incremented each time [`Terminal::draw`] is called and wraps
-    /// when it is greater than [`std::usize::MAX`].
-    frame_index: usize,
 }
 
 /// Represents a consistent terminal interface for rendering.
@@ -113,31 +69,6 @@ where
     cursor_position: Option<(u16, u16)>,
 }
 
-/// RenderArgs are the arguments required to render a [`Widget`].
-pub struct RenderArgs {
-    /// Area where the widget will be rendered.
-    area: Rect,
-    /// Optional id that can be used to uniquely identify the provided [`Widget`].
-    id: Option<String>,
-}
-
-impl From<Rect> for RenderArgs {
-    fn from(area: Rect) -> RenderArgs {
-        RenderArgs { area, id: None }
-    }
-}
-
-impl RenderArgs {
-    /// Set the [`Widget`] id.
-    pub fn id<S>(mut self, id: S) -> Self
-    where
-        S: Into<String>,
-    {
-        self.id = Some(id.into());
-        self
-    }
-}
-
 impl<'a, B> Frame<'a, B>
 where
     B: Backend,
@@ -151,93 +82,55 @@ where
     ///
     /// # Examples
     ///
-    /// ```rust,no_run
-    /// # use std::io;
+    /// ```rust
     /// # use tui::Terminal;
-    /// # use tui::backend::TermionBackend;
+    /// # use tui::backend::TestBackend;
     /// # use tui::layout::Rect;
     /// # use tui::widgets::Block;
-    /// # let stdout = io::stdout();
-    /// # let backend = TermionBackend::new(stdout);
+    /// # let backend = TestBackend::new(5, 5);
     /// # let mut terminal = Terminal::new(backend).unwrap();
     /// let block = Block::default();
     /// let area = Rect::new(0, 0, 5, 5);
     /// let mut frame = terminal.get_frame();
     /// frame.render_widget(block, area);
     /// ```
-    ///
-    /// If you happen to render two or more widgets using the same render call, you may want to
-    /// associate them with a unique id so they do not share any internal state.
-    ///
-    /// For example, let say your app shows a list of songs of a given album:
-    /// ```rust,no_run
-    /// # use std::{collections::HashMap, io};
-    /// # use tui::{Terminal, RenderArgs};
-    /// # use tui::backend::TermionBackend;
-    /// # use tui::layout::Rect;
-    /// # use tui::widgets::{Block, List, ListItem};
-    /// # let stdout = io::stdout();
-    /// # let backend = TermionBackend::new(stdout);
-    /// # let mut terminal = Terminal::new(backend).unwrap();
-    /// struct App {
-    ///    albums: HashMap<String, Vec<String>>,
-    ///    selected_album: String
-    /// }
-    /// # let app = App {
-    /// #    albums: HashMap::new(),
-    /// #    selected_album: String::new(),
-    /// # };
-    /// terminal.draw(|f| {
-    ///     let songs: Vec<ListItem> = app.albums[&app.selected_album]
-    ///         .iter()
-    ///         .map(|song| ListItem::new(song.as_ref()))
-    ///         .collect();
-    ///     let song_list = List::new(songs)
-    ///         .block(Block::default().title(app.selected_album.as_ref()));
-    ///     // Giving a unique id here makes sure the list state is reset whenever the album
-    ///     // currently displayed changes.
-    ///     let args = RenderArgs::from(f.size()).id(app.selected_album.clone());
-    ///     f.render_widget(song_list, args);
-    /// });
-    /// ```
-    #[track_caller]
-    pub fn render_widget<W, R>(&mut self, widget: W, args: R)
+    pub fn render_widget<W>(&mut self, widget: W, area: Rect)
     where
         W: Widget,
-        W::State: 'static + Default,
-        R: Into<RenderArgs>,
     {
-        // Fetch the previous internal state of the widget (or initialize it with a default value).
-        let args: RenderArgs = args.into();
-        let location = Location::caller();
-        let key = StateKey {
-            call_location: CallLocation(location),
-            id: args.id,
-        };
-        let entry = self
-            .terminal
-            .widget_states
-            .entry(key)
-            .or_insert_with(|| StateEntry {
-                state: Box::new(<W::State>::default()),
-                frame_index: 0,
-            });
-        let state: &mut W::State = entry
-            .state
-            .downcast_mut()
-            .expect("The state associated to a widget is not of an expected type");
+        widget.render(area, self.terminal.current_buffer_mut());
+    }
 
-        // Update the frame index to communicate that it was used during the current draw call.
-        entry.frame_index = self.terminal.frame_index;
-
-        // Render the widget
-        let buffer = &mut self.terminal.buffers[self.terminal.current];
-        let mut context = RenderContext {
-            area: args.area,
-            buffer,
-            state,
-        };
-        widget.render(&mut context);
+    /// Render a [`StatefulWidget`] to the current buffer using [`StatefulWidget::render`].
+    ///
+    /// The last argument should be an instance of the [`StatefulWidget::State`] associated to the
+    /// given [`StatefulWidget`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use tui::Terminal;
+    /// # use tui::backend::TestBackend;
+    /// # use tui::layout::Rect;
+    /// # use tui::widgets::{List, ListItem, ListState};
+    /// # let backend = TestBackend::new(5, 5);
+    /// # let mut terminal = Terminal::new(backend).unwrap();
+    /// let mut state = ListState::default();
+    /// state.select(Some(1));
+    /// let items = vec![
+    ///     ListItem::new("Item 1"),
+    ///     ListItem::new("Item 2"),
+    /// ];
+    /// let list = List::new(items);
+    /// let area = Rect::new(0, 0, 5, 5);
+    /// let mut frame = terminal.get_frame();
+    /// frame.render_stateful_widget(list, area, &mut state);
+    /// ```
+    pub fn render_stateful_widget<W>(&mut self, widget: W, area: Rect, state: &mut W::State)
+    where
+        W: StatefulWidget,
+    {
+        widget.render(area, self.terminal.current_buffer_mut(), state);
     }
 
     /// After drawing this frame, make the cursor visible and put it at the specified (x, y)
@@ -303,8 +196,6 @@ where
             current: 0,
             hidden_cursor: false,
             viewport: options.viewport,
-            widget_states: HashMap::new(),
-            frame_index: 0,
         })
     }
 
@@ -390,12 +281,6 @@ where
         self.buffers[1 - self.current].reset();
         self.current = 1 - self.current;
 
-        // Clean states that were not used in this frame
-        let frame_index = self.frame_index;
-        self.widget_states
-            .retain(|_, v| v.frame_index == frame_index);
-        self.frame_index = self.frame_index.wrapping_add(1);
-
         // Flush
         self.backend.flush()?;
         Ok(CompletedFrame {

src/text.rs

@@ -194,15 +194,9 @@ impl<'a> From<&'a str> for Span<'a> {
 }
 
 /// A string composed of clusters of graphemes, each with their own style.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Default)]
 pub struct Spans<'a>(pub Vec<Span<'a>>);
 
-impl<'a> Default for Spans<'a> {
-    fn default() -> Spans<'a> {
-        Spans(Vec::new())
-    }
-}
-
 impl<'a> Spans<'a> {
     /// Returns the width of the underlying string.
     ///
@@ -279,17 +273,11 @@ impl<'a> From<Spans<'a>> for String {
 /// text.extend(Text::styled("Some more lines\nnow with more style!", style));
 /// assert_eq!(6, text.height());
 /// ```
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Default)]
 pub struct Text<'a> {
     pub lines: Vec<Spans<'a>>,
 }
 
-impl<'a> Default for Text<'a> {
-    fn default() -> Text<'a> {
-        Text { lines: Vec::new() }
-    }
-}
-
 impl<'a> Text<'a> {
     /// Create some text (potentially multiple lines) with no style.
     ///
@@ -398,6 +386,12 @@ impl<'a> From<&'a str> for Text<'a> {
     }
 }
 
+impl<'a> From<Cow<'a, str>> for Text<'a> {
+    fn from(s: Cow<'a, str>) -> Text<'a> {
+        Text::raw(s)
+    }
+}
+
 impl<'a> From<Span<'a>> for Text<'a> {
     fn from(span: Span<'a>) -> Text<'a> {
         Text {

src/widgets/barchart.rs

@@ -1,7 +1,9 @@
 use crate::{
+    buffer::Buffer,
+    layout::Rect,
     style::Style,
     symbols,
-    widgets::{Block, RenderContext, Widget},
+    widgets::{Block, Widget},
 };
 use std::cmp::min;
 use unicode_width::UnicodeWidthStr;
@@ -125,22 +127,16 @@ impl<'a> BarChart<'a> {
 }
 
 impl<'a> Widget for BarChart<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        buf.set_style(area, self.style);
 
         let chart_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if chart_area.height < 2 {
@@ -180,13 +176,12 @@ impl<'a> Widget for BarChart<'a> {
                 };
 
                 for x in 0..self.bar_width {
-                    ctx.buffer
-                        .get_mut(
-                            chart_area.left() + i as u16 * (self.bar_width + self.bar_gap) + x,
-                            chart_area.top() + j,
-                        )
-                        .set_symbol(symbol)
-                        .set_style(self.bar_style);
+                    buf.get_mut(
+                        chart_area.left() + i as u16 * (self.bar_width + self.bar_gap) + x,
+                        chart_area.top() + j,
+                    )
+                    .set_symbol(symbol)
+                    .set_style(self.bar_style);
                 }
 
                 if d.1 > 8 {
@@ -202,7 +197,7 @@ impl<'a> Widget for BarChart<'a> {
                 let value_label = &self.values[i];
                 let width = value_label.width() as u16;
                 if width < self.bar_width {
-                    ctx.buffer.set_string(
+                    buf.set_string(
                         chart_area.left()
                             + i as u16 * (self.bar_width + self.bar_gap)
                             + (self.bar_width - width) / 2,
@@ -212,7 +207,7 @@ impl<'a> Widget for BarChart<'a> {
                     );
                 }
             }
-            ctx.buffer.set_stringn(
+            buf.set_stringn(
                 chart_area.left() + i as u16 * (self.bar_width + self.bar_gap),
                 chart_area.bottom() - 1,
                 label,

src/widgets/block.rs

@@ -1,9 +1,10 @@
 use crate::{
-    layout::Rect,
+    buffer::Buffer,
+    layout::{Alignment, Rect},
     style::Style,
     symbols::line,
     text::{Span, Spans},
-    widgets::{Borders, RenderContext, Widget},
+    widgets::{Borders, Widget},
 };
 
 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -44,6 +45,9 @@ impl BorderType {
 pub struct Block<'a> {
     /// Optional title place on the upper left of the block
     title: Option<Spans<'a>>,
+    /// Title alignment. The default is top left of the block, but one can choose to place
+    /// title in the top middle, or top right of the block
+    title_alignment: Alignment,
     /// Visible borders
     borders: Borders,
     /// Border style
@@ -59,6 +63,7 @@ impl<'a> Default for Block<'a> {
     fn default() -> Block<'a> {
         Block {
             title: None,
+            title_alignment: Alignment::Left,
             borders: Borders::NONE,
             border_style: Default::default(),
             border_type: BorderType::Plain,
@@ -88,6 +93,11 @@ impl<'a> Block<'a> {
         self
     }
 
+    pub fn title_alignment(mut self, alignment: Alignment) -> Block<'a> {
+        self.title_alignment = alignment;
+        self
+    }
+
     pub fn border_style(mut self, style: Style) -> Block<'a> {
         self.border_style = style;
         self
@@ -130,46 +140,40 @@ impl<'a> Block<'a> {
 }
 
 impl<'a> Widget for Block<'a> {
-    type State = ();
-
-    fn render(self, ctx: &mut RenderContext<Self::State>) {
-        if ctx.area.area() == 0 {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        if area.area() == 0 {
             return;
         }
-        ctx.buffer.set_style(ctx.area, self.style);
+        buf.set_style(area, self.style);
         let symbols = BorderType::line_symbols(self.border_type);
 
         // Sides
         if self.borders.intersects(Borders::LEFT) {
-            for y in ctx.area.top()..ctx.area.bottom() {
-                ctx.buffer
-                    .get_mut(ctx.area.left(), y)
+            for y in area.top()..area.bottom() {
+                buf.get_mut(area.left(), y)
                     .set_symbol(symbols.vertical)
                     .set_style(self.border_style);
             }
         }
         if self.borders.intersects(Borders::TOP) {
-            for x in ctx.area.left()..ctx.area.right() {
-                ctx.buffer
-                    .get_mut(x, ctx.area.top())
+            for x in area.left()..area.right() {
+                buf.get_mut(x, area.top())
                     .set_symbol(symbols.horizontal)
                     .set_style(self.border_style);
             }
         }
         if self.borders.intersects(Borders::RIGHT) {
-            let x = ctx.area.right() - 1;
-            for y in ctx.area.top()..ctx.area.bottom() {
-                ctx.buffer
-                    .get_mut(x, y)
+            let x = area.right() - 1;
+            for y in area.top()..area.bottom() {
+                buf.get_mut(x, y)
                     .set_symbol(symbols.vertical)
                     .set_style(self.border_style);
             }
         }
         if self.borders.intersects(Borders::BOTTOM) {
-            let y = ctx.area.bottom() - 1;
-            for x in ctx.area.left()..ctx.area.right() {
-                ctx.buffer
-                    .get_mut(x, y)
+            let y = area.bottom() - 1;
+            for x in area.left()..area.right() {
+                buf.get_mut(x, y)
                     .set_symbol(symbols.horizontal)
                     .set_style(self.border_style);
             }
@@ -177,44 +181,58 @@ impl<'a> Widget for Block<'a> {
 
         // Corners
         if self.borders.contains(Borders::RIGHT | Borders::BOTTOM) {
-            ctx.buffer
-                .get_mut(ctx.area.right() - 1, ctx.area.bottom() - 1)
+            buf.get_mut(area.right() - 1, area.bottom() - 1)
                 .set_symbol(symbols.bottom_right)
                 .set_style(self.border_style);
         }
         if self.borders.contains(Borders::RIGHT | Borders::TOP) {
-            ctx.buffer
-                .get_mut(ctx.area.right() - 1, ctx.area.top())
+            buf.get_mut(area.right() - 1, area.top())
                 .set_symbol(symbols.top_right)
                 .set_style(self.border_style);
         }
         if self.borders.contains(Borders::LEFT | Borders::BOTTOM) {
-            ctx.buffer
-                .get_mut(ctx.area.left(), ctx.area.bottom() - 1)
+            buf.get_mut(area.left(), area.bottom() - 1)
                 .set_symbol(symbols.bottom_left)
                 .set_style(self.border_style);
         }
         if self.borders.contains(Borders::LEFT | Borders::TOP) {
-            ctx.buffer
-                .get_mut(ctx.area.left(), ctx.area.top())
+            buf.get_mut(area.left(), area.top())
                 .set_symbol(symbols.top_left)
                 .set_style(self.border_style);
         }
 
+        // Title
         if let Some(title) = self.title {
-            let lx = if self.borders.intersects(Borders::LEFT) {
+            let left_border_dx = if self.borders.intersects(Borders::LEFT) {
                 1
             } else {
                 0
             };
-            let rx = if self.borders.intersects(Borders::RIGHT) {
+
+            let right_border_dx = if self.borders.intersects(Borders::RIGHT) {
                 1
             } else {
                 0
             };
-            let width = ctx.area.width.saturating_sub(lx).saturating_sub(rx);
-            ctx.buffer
-                .set_spans(ctx.area.left() + lx, ctx.area.top(), &title, width);
+
+            let title_area_width = area
+                .width
+                .saturating_sub(left_border_dx)
+                .saturating_sub(right_border_dx);
+
+            let title_dx = match self.title_alignment {
+                Alignment::Left => left_border_dx,
+                Alignment::Center => area.width.saturating_sub(title.width() as u16) / 2,
+                Alignment::Right => area
+                    .width
+                    .saturating_sub(title.width() as u16)
+                    .saturating_sub(right_border_dx),
+            };
+
+            let title_x = area.left() + title_dx;
+            let title_y = area.top();
+
+            buf.set_spans(title_x, title_y, &title, title_area_width);
         }
     }
 }
@@ -517,5 +535,39 @@ mod tests {
                 height: 0,
             },
         );
+        assert_eq!(
+            Block::default()
+                .title("Test")
+                .title_alignment(Alignment::Center)
+                .inner(Rect {
+                    x: 0,
+                    y: 0,
+                    width: 0,
+                    height: 1,
+                }),
+            Rect {
+                x: 0,
+                y: 1,
+                width: 0,
+                height: 0,
+            },
+        );
+        assert_eq!(
+            Block::default()
+                .title("Test")
+                .title_alignment(Alignment::Right)
+                .inner(Rect {
+                    x: 0,
+                    y: 0,
+                    width: 0,
+                    height: 1,
+                }),
+            Rect {
+                x: 0,
+                y: 1,
+                width: 0,
+                height: 0,
+            },
+        );
     }
 }

src/widgets/canvas/mod.rs

@@ -10,9 +10,12 @@ pub use self::points::Points;
 pub use self::rectangle::Rectangle;
 
 use crate::{
+    buffer::Buffer,
+    layout::Rect,
     style::{Color, Style},
     symbols,
-    widgets::{Block, RenderContext, Widget},
+    text::Spans,
+    widgets::{Block, Widget},
 };
 use std::fmt::Debug;
 
@@ -24,10 +27,9 @@ pub trait Shape {
 /// Label to draw some text on the canvas
 #[derive(Debug, Clone)]
 pub struct Label<'a> {
-    pub x: f64,
-    pub y: f64,
-    pub text: &'a str,
-    pub color: Color,
+    x: f64,
+    y: f64,
+    spans: Spans<'a>,
 }
 
 #[derive(Debug, Clone)]
@@ -291,8 +293,15 @@ impl<'a> Context<'a> {
     }
 
     /// Print a string on the canvas at the given position
-    pub fn print(&mut self, x: f64, y: f64, text: &'a str, color: Color) {
-        self.labels.push(Label { x, y, text, color });
+    pub fn print<T>(&mut self, x: f64, y: f64, spans: T)
+    where
+        T: Into<Spans<'a>>,
+    {
+        self.labels.push(Label {
+            x,
+            y,
+            spans: spans.into(),
+        });
     }
 
     /// Push the last layer if necessary
@@ -421,22 +430,18 @@ impl<'a, F> Widget for Canvas<'a, F>
 where
     F: Fn(&mut Context),
 {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
         let canvas_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
+        buf.set_style(canvas_area, Style::default().bg(self.background_color));
+
         let width = canvas_area.width as usize;
 
         let painter = match self.painter {
@@ -445,7 +450,7 @@ where
         };
 
         // Create a blank context that match the size of the canvas
-        let mut canvas_ctx = Context::new(
+        let mut ctx = Context::new(
             canvas_area.width,
             canvas_area.height,
             self.x_bounds,
@@ -453,11 +458,11 @@ where
             self.marker,
         );
         // Paint to this context
-        painter(&mut canvas_ctx);
-        canvas_ctx.finish();
+        painter(&mut ctx);
+        ctx.finish();
 
         // Retreive painted points for each layer
-        for layer in canvas_ctx.layers {
+        for layer in ctx.layers {
             for (i, (ch, color)) in layer
                 .string
                 .chars()
@@ -466,17 +471,14 @@ where
             {
                 if ch != ' ' && ch != '\u{2800}' {
                     let (x, y) = (i % width, i / width);
-                    ctx.buffer
-                        .get_mut(x as u16 + canvas_area.left(), y as u16 + canvas_area.top())
+                    buf.get_mut(x as u16 + canvas_area.left(), y as u16 + canvas_area.top())
                         .set_char(ch)
-                        .set_fg(color)
-                        .set_bg(self.background_color);
+                        .set_fg(color);
                 }
             }
         }
 
         // Finally draw the labels
-        let style = Style::default().bg(self.background_color);
         let left = self.x_bounds[0];
         let right = self.x_bounds[1];
         let top = self.y_bounds[1];
@@ -488,20 +490,14 @@ where
             let height = f64::from(canvas_area.height - 1);
             (width, height)
         };
-        for label in canvas_ctx
+        for label in ctx
             .labels
             .iter()
             .filter(|l| l.x >= left && l.x <= right && l.y <= top && l.y >= bottom)
         {
             let x = ((label.x - left) * resolution.0 / width) as u16 + canvas_area.left();
             let y = ((top - label.y) * resolution.1 / height) as u16 + canvas_area.top();
-            ctx.buffer.set_stringn(
-                x,
-                y,
-                label.text,
-                (canvas_area.right() - x) as usize,
-                style.fg(label.color),
-            );
+            buf.set_spans(x, y, &label.spans, canvas_area.right() - x);
         }
     }
 }

src/widgets/canvas/world.rs

@@ -6122,6 +6122,7 @@ pub static WORLD_LOW_RESOLUTION: [(f64, f64); 1166] = [
     (120.43, 16.43),
     (121.72, 18.40),
     (125.34, 9.79),
+    #[allow(clippy::approx_constant)]
     (125.56, 6.28),
     (122.38, 7.00),
     (125.10, 9.38),

src/widgets/chart.rs

@@ -1,15 +1,19 @@
+use std::{borrow::Cow, cmp::max};
+
+use unicode_width::UnicodeWidthStr;
+
+use crate::layout::Alignment;
 use crate::{
+    buffer::Buffer,
     layout::{Constraint, Rect},
     style::{Color, Style},
     symbols,
     text::{Span, Spans},
     widgets::{
         canvas::{Canvas, Line, Points},
-        Block, Borders, RenderContext, Widget,
+        Block, Borders, Widget,
     },
 };
-use std::{borrow::Cow, cmp::max};
-use unicode_width::UnicodeWidthStr;
 
 /// An X or Y axis for the chart widget
 #[derive(Debug, Clone)]
@@ -22,6 +26,8 @@ pub struct Axis<'a> {
     labels: Option<Vec<Span<'a>>>,
     /// The style used to draw the axis itself
     style: Style,
+    /// The alignment of the labels of the Axis
+    labels_alignment: Alignment,
 }
 
 impl<'a> Default for Axis<'a> {
@@ -31,6 +37,7 @@ impl<'a> Default for Axis<'a> {
             bounds: [0.0, 0.0],
             labels: None,
             style: Default::default(),
+            labels_alignment: Alignment::Left,
         }
     }
 }
@@ -70,6 +77,15 @@ impl<'a> Axis<'a> {
         self.style = style;
         self
     }
+
+    /// Defines the alignment of the labels of the axis.
+    /// The alignment behaves differently based on the axis:
+    /// - Y-Axis: The labels are aligned within the area on the left of the axis
+    /// - X-Axis: The first X-axis label is aligned relative to the Y-axis
+    pub fn labels_alignment(mut self, alignment: Alignment) -> Axis<'a> {
+        self.labels_alignment = alignment;
+        self
+    }
 }
 
 /// Used to determine which style of graphing to use
@@ -140,7 +156,7 @@ impl<'a> Dataset<'a> {
 
 /// A container that holds all the infos about where to display each elements of the chart (axis,
 /// labels, legend, ...).
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Default)]
 struct ChartLayout {
     /// Location of the title of the x axis
     title_x: Option<(u16, u16)>,
@@ -160,21 +176,6 @@ struct ChartLayout {
     graph_area: Rect,
 }
 
-impl Default for ChartLayout {
-    fn default() -> ChartLayout {
-        ChartLayout {
-            title_x: None,
-            title_y: None,
-            label_x: None,
-            label_y: None,
-            axis_x: None,
-            axis_y: None,
-            legend_area: None,
-            graph_area: Rect::default(),
-        }
-    }
-}
-
 /// A widget to plot one or more dataset in a cartesian coordinate system
 ///
 /// # Examples
@@ -295,18 +296,8 @@ impl<'a> Chart<'a> {
             y -= 1;
         }
 
-        if let Some(ref y_labels) = self.y_axis.labels {
-            let mut max_width = y_labels.iter().map(Span::width).max().unwrap_or_default() as u16;
-            if let Some(ref x_labels) = self.x_axis.labels {
-                if !x_labels.is_empty() {
-                    max_width = max(max_width, x_labels[0].content.width() as u16);
-                }
-            }
-            if x + max_width < area.right() {
-                layout.label_y = Some(x);
-                x += max_width;
-            }
-        }
+        layout.label_y = self.y_axis.labels.as_ref().and(Some(x));
+        x += self.max_width_of_labels_left_of_y_axis(area, self.y_axis.labels.is_some());
 
         if self.x_axis.labels.is_some() && y > area.top() {
             layout.axis_x = Some(y);
@@ -361,32 +352,163 @@ impl<'a> Chart<'a> {
         }
         layout
     }
+
+    fn max_width_of_labels_left_of_y_axis(&self, area: Rect, has_y_axis: bool) -> u16 {
+        let mut max_width = self
+            .y_axis
+            .labels
+            .as_ref()
+            .map(|l| l.iter().map(Span::width).max().unwrap_or_default() as u16)
+            .unwrap_or_default();
+
+        if let Some(first_x_label) = self.x_axis.labels.as_ref().and_then(|labels| labels.get(0)) {
+            let first_label_width = first_x_label.content.width() as u16;
+            let width_left_of_y_axis = match self.x_axis.labels_alignment {
+                Alignment::Left => {
+                    // The last character of the label should be below the Y-Axis when it exists, not on its left
+                    let y_axis_offset = if has_y_axis { 1 } else { 0 };
+                    first_label_width.saturating_sub(y_axis_offset)
+                }
+                Alignment::Center => first_label_width / 2,
+                Alignment::Right => 0,
+            };
+            max_width = max(max_width, width_left_of_y_axis);
+        }
+        // labels of y axis and first label of x axis can take at most 1/3rd of the total width
+        max_width.min(area.width / 3)
+    }
+
+    fn render_x_labels(
+        &mut self,
+        buf: &mut Buffer,
+        layout: &ChartLayout,
+        chart_area: Rect,
+        graph_area: Rect,
+    ) {
+        let y = match layout.label_x {
+            Some(y) => y,
+            None => return,
+        };
+        let labels = self.x_axis.labels.as_ref().unwrap();
+        let labels_len = labels.len() as u16;
+        if labels_len < 2 {
+            return;
+        }
+
+        let width_between_ticks = graph_area.width / labels_len;
+
+        let label_area = self.first_x_label_area(
+            y,
+            labels.first().unwrap().width() as u16,
+            width_between_ticks,
+            chart_area,
+            graph_area,
+        );
+
+        let label_alignment = match self.x_axis.labels_alignment {
+            Alignment::Left => Alignment::Right,
+            Alignment::Center => Alignment::Center,
+            Alignment::Right => Alignment::Left,
+        };
+
+        Self::render_label(buf, labels.first().unwrap(), label_area, label_alignment);
+
+        for (i, label) in labels[1..labels.len() - 1].iter().enumerate() {
+            // We add 1 to x (and width-1 below) to leave at least one space before each intermediate labels
+            let x = graph_area.left() + (i + 1) as u16 * width_between_ticks + 1;
+            let label_area = Rect::new(x, y, width_between_ticks.saturating_sub(1), 1);
+
+            Self::render_label(buf, label, label_area, Alignment::Center);
+        }
+
+        let x = graph_area.right() - width_between_ticks;
+        let label_area = Rect::new(x, y, width_between_ticks, 1);
+        // The last label should be aligned Right to be at the edge of the graph area
+        Self::render_label(buf, labels.last().unwrap(), label_area, Alignment::Right);
+    }
+
+    fn first_x_label_area(
+        &self,
+        y: u16,
+        label_width: u16,
+        max_width_after_y_axis: u16,
+        chart_area: Rect,
+        graph_area: Rect,
+    ) -> Rect {
+        let (min_x, max_x) = match self.x_axis.labels_alignment {
+            Alignment::Left => (chart_area.left(), graph_area.left()),
+            Alignment::Center => (
+                chart_area.left(),
+                graph_area.left() + max_width_after_y_axis.min(label_width),
+            ),
+            Alignment::Right => (
+                graph_area.left().saturating_sub(1),
+                graph_area.left() + max_width_after_y_axis,
+            ),
+        };
+
+        Rect::new(min_x, y, max_x - min_x, 1)
+    }
+
+    fn render_label(buf: &mut Buffer, label: &Span, label_area: Rect, alignment: Alignment) {
+        let label_width = label.width() as u16;
+        let bounded_label_width = label_area.width.min(label_width);
+
+        let x = match alignment {
+            Alignment::Left => label_area.left(),
+            Alignment::Center => label_area.left() + label_area.width / 2 - bounded_label_width / 2,
+            Alignment::Right => label_area.right() - bounded_label_width,
+        };
+
+        buf.set_span(x, label_area.top(), label, bounded_label_width);
+    }
+
+    fn render_y_labels(
+        &mut self,
+        buf: &mut Buffer,
+        layout: &ChartLayout,
+        chart_area: Rect,
+        graph_area: Rect,
+    ) {
+        let x = match layout.label_y {
+            Some(x) => x,
+            None => return,
+        };
+        let labels = self.y_axis.labels.as_ref().unwrap();
+        let labels_len = labels.len() as u16;
+        for (i, label) in labels.iter().enumerate() {
+            let dy = i as u16 * (graph_area.height - 1) / (labels_len - 1);
+            if dy < graph_area.bottom() {
+                let label_area = Rect::new(
+                    x,
+                    graph_area.bottom().saturating_sub(1) - dy,
+                    (graph_area.left() - chart_area.left()).saturating_sub(1),
+                    1,
+                );
+                Self::render_label(buf, label, label_area, self.y_axis.labels_alignment);
+            }
+        }
+    }
 }
 
 impl<'a> Widget for Chart<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        if ctx.area.area() == 0 {
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        if area.area() == 0 {
             return;
         }
-        ctx.buffer.set_style(ctx.area, self.style);
+        buf.set_style(area, self.style);
         // Sample the style of the entire widget. This sample will be used to reset the style of
         // the cells that are part of the components put on top of the grah area (i.e legend and
         // axis names).
-        let original_style = ctx.buffer.get(ctx.area.left(), ctx.area.top()).style();
+        let original_style = buf.get(area.left(), area.top()).style();
 
         let chart_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         let layout = self.layout(chart_area);
@@ -395,43 +517,12 @@ impl<'a> Widget for Chart<'a> {
             return;
         }
 
-        if let Some(y) = layout.label_x {
-            let labels = self.x_axis.labels.unwrap();
-            let total_width = labels.iter().map(Span::width).sum::<usize>() as u16;
-            let labels_len = labels.len() as u16;
-            if total_width < graph_area.width && labels_len > 1 {
-                for (i, label) in labels.iter().enumerate() {
-                    ctx.buffer.set_span(
-                        graph_area.left() + i as u16 * (graph_area.width - 1) / (labels_len - 1)
-                            - label.content.width() as u16,
-                        y,
-                        label,
-                        label.width() as u16,
-                    );
-                }
-            }
-        }
-
-        if let Some(x) = layout.label_y {
-            let labels = self.y_axis.labels.unwrap();
-            let labels_len = labels.len() as u16;
-            for (i, label) in labels.iter().enumerate() {
-                let dy = i as u16 * (graph_area.height - 1) / (labels_len - 1);
-                if dy < graph_area.bottom() {
-                    ctx.buffer.set_span(
-                        x,
-                        graph_area.bottom() - 1 - dy,
-                        label,
-                        label.width() as u16,
-                    );
-                }
-            }
-        }
+        self.render_x_labels(buf, &layout, chart_area, graph_area);
+        self.render_y_labels(buf, &layout, chart_area, graph_area);
 
         if let Some(y) = layout.axis_x {
             for x in graph_area.left()..graph_area.right() {
-                ctx.buffer
-                    .get_mut(x, y)
+                buf.get_mut(x, y)
                     .set_symbol(symbols::line::HORIZONTAL)
                     .set_style(self.x_axis.style);
             }
@@ -439,8 +530,7 @@ impl<'a> Widget for Chart<'a> {
 
         if let Some(x) = layout.axis_y {
             for y in graph_area.top()..graph_area.bottom() {
-                ctx.buffer
-                    .get_mut(x, y)
+                buf.get_mut(x, y)
                     .set_symbol(symbols::line::VERTICAL)
                     .set_style(self.y_axis.style);
             }
@@ -448,8 +538,7 @@ impl<'a> Widget for Chart<'a> {
 
         if let Some(y) = layout.axis_x {
             if let Some(x) = layout.axis_y {
-                ctx.buffer
-                    .get_mut(x, y)
+                buf.get_mut(x, y)
                     .set_symbol(symbols::line::BOTTOM_LEFT)
                     .set_style(self.x_axis.style);
             }
@@ -478,24 +567,16 @@ impl<'a> Widget for Chart<'a> {
                         }
                     }
                 })
-                .render(&mut RenderContext {
-                    area: graph_area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                .render(graph_area, buf);
         }
 
         if let Some(legend_area) = layout.legend_area {
-            ctx.buffer.set_style(legend_area, original_style);
+            buf.set_style(legend_area, original_style);
             Block::default()
                 .borders(Borders::ALL)
-                .render(&mut RenderContext {
-                    area: legend_area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                .render(legend_area, buf);
             for (i, dataset) in self.datasets.iter().enumerate() {
-                ctx.buffer.set_string(
+                buf.set_string(
                     legend_area.x + 1,
                     legend_area.y + 1 + i as u16,
                     &dataset.name,
@@ -507,7 +588,7 @@ impl<'a> Widget for Chart<'a> {
         if let Some((x, y)) = layout.title_x {
             let title = self.x_axis.title.unwrap();
             let width = graph_area.right().saturating_sub(x);
-            ctx.buffer.set_style(
+            buf.set_style(
                 Rect {
                     x,
                     y,
@@ -516,13 +597,13 @@ impl<'a> Widget for Chart<'a> {
                 },
                 original_style,
             );
-            ctx.buffer.set_spans(x, y, &title, width);
+            buf.set_spans(x, y, &title, width);
         }
 
         if let Some((x, y)) = layout.title_y {
             let title = self.y_axis.title.unwrap();
             let width = graph_area.right().saturating_sub(x);
-            ctx.buffer.set_style(
+            buf.set_style(
                 Rect {
                     x,
                     y,
@@ -531,7 +612,7 @@ impl<'a> Widget for Chart<'a> {
                 },
                 original_style,
             );
-            ctx.buffer.set_spans(x, y, &title, width);
+            buf.set_spans(x, y, &title, width);
         }
     }
 }

src/widgets/clear.rs

@@ -1,6 +1,9 @@
-use crate::widgets::{RenderContext, Widget};
+use crate::{buffer::Buffer, layout::Rect, widgets::Widget};
 
-/// A widget to to clear/reset a certain area to allow overdrawing (e.g. for popups)
+/// A widget to clear/reset a certain area to allow overdrawing (e.g. for popups).
+///
+/// This widget **cannot be used to clear the terminal on the first render** as `tui` assumes the
+/// render area is empty. Use [`crate::Terminal::clear`] instead.
 ///
 /// # Examples
 ///
@@ -24,12 +27,10 @@ use crate::widgets::{RenderContext, Widget};
 pub struct Clear;
 
 impl Widget for Clear {
-    type State = ();
-
-    fn render(self, ctx: &mut RenderContext<Self::State>) {
-        for x in ctx.area.left()..ctx.area.right() {
-            for y in ctx.area.top()..ctx.area.bottom() {
-                ctx.buffer.get_mut(x, y).reset();
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        for x in area.left()..area.right() {
+            for y in area.top()..area.bottom() {
+                buf.get_mut(x, y).reset();
             }
         }
     }

src/widgets/gauge.rs

@@ -1,8 +1,10 @@
 use crate::{
+    buffer::Buffer,
+    layout::Rect,
     style::{Color, Style},
     symbols,
     text::{Span, Spans},
-    widgets::{Block, RenderContext, Widget},
+    widgets::{Block, Widget},
 };
 
 /// A widget to display a task progress.
@@ -58,7 +60,7 @@ impl<'a> Gauge<'a> {
     /// Sets ratio ([0.0, 1.0]) directly.
     pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
         assert!(
-            ratio <= 1.0 && ratio >= 0.0,
+            (0.0..=1.0).contains(&ratio),
             "Ratio should be between 0 and 1 inclusively."
         );
         self.ratio = ratio;
@@ -90,80 +92,60 @@ impl<'a> Gauge<'a> {
 }
 
 impl<'a> Widget for Gauge<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        buf.set_style(area, self.style);
         let gauge_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
-        ctx.buffer.set_style(gauge_area, self.gauge_style);
+        buf.set_style(gauge_area, self.gauge_style);
         if gauge_area.height < 1 {
             return;
         }
 
-        let center = gauge_area.height / 2 + gauge_area.top();
-        let width = f64::from(gauge_area.width) * self.ratio;
-        //go to regular rounding behavior if we're not using unicode blocks
-        let end = gauge_area.left()
-            + if self.use_unicode {
-                width.floor() as u16
-            } else {
-                width.round() as u16
-            };
-        // Label
-        let ratio = self.ratio;
-        let label = self
-            .label
-            .unwrap_or_else(|| Span::from(format!("{}%", (ratio * 100.0).round())));
+        // compute label value and its position
+        // label is put at the center of the gauge_area
+        let label = {
+            let pct = f64::round(self.ratio * 100.0);
+            self.label
+                .unwrap_or_else(|| Span::from(format!("{}%", pct)))
+        };
+        let clamped_label_width = gauge_area.width.min(label.width() as u16);
+        let label_col = gauge_area.left() + (gauge_area.width - clamped_label_width) / 2;
+        let label_row = gauge_area.top() + gauge_area.height / 2;
+
+        // the gauge will be filled proportionally to the ratio
+        let filled_width = f64::from(gauge_area.width) * self.ratio;
+        let end = if self.use_unicode {
+            gauge_area.left() + filled_width.floor() as u16
+        } else {
+            gauge_area.left() + filled_width.round() as u16
+        };
         for y in gauge_area.top()..gauge_area.bottom() {
-            // Gauge
+            // render the filled area (left to end)
             for x in gauge_area.left()..end {
-                ctx.buffer.get_mut(x, y).set_symbol(" ");
-            }
-
-            //set unicode block
-            if self.use_unicode && self.ratio < 1.0 {
-                ctx.buffer
-                    .get_mut(end, y)
-                    .set_symbol(get_unicode_block(width % 1.0));
-            }
-
-            let mut color_end = end;
-
-            if y == center {
-                let label_width = label.width() as u16;
-                let middle = (gauge_area.width - label_width) / 2 + gauge_area.left();
-                ctx.buffer
-                    .set_span(middle, y, &label, gauge_area.right() - middle);
-                if self.use_unicode && end >= middle && end < middle + label_width {
-                    color_end = gauge_area.left() + (width.round() as u16); //set color on the label to the rounded gauge level
-                }
-            }
-
-            // Fix colors
-            for x in gauge_area.left()..color_end {
-                ctx.buffer
-                    .get_mut(x, y)
+                // spaces are needed to apply the background styling
+                buf.get_mut(x, y)
+                    .set_symbol(" ")
                     .set_fg(self.gauge_style.bg.unwrap_or(Color::Reset))
                     .set_bg(self.gauge_style.fg.unwrap_or(Color::Reset));
             }
+            if self.use_unicode && self.ratio < 1.0 {
+                buf.get_mut(end, y)
+                    .set_symbol(get_unicode_block(filled_width % 1.0));
+            }
         }
+        // set the span
+        buf.set_span(label_col, label_row, &label, clamped_label_width);
     }
 }
 
 fn get_unicode_block<'a>(frac: f64) -> &'a str {
     match (frac * 8.0).round() as u16 {
-        //get how many eighths the fraction is closest to
         1 => symbols::block::ONE_EIGHTH,
         2 => symbols::block::ONE_QUARTER,
         3 => symbols::block::THREE_EIGHTHS,
@@ -220,7 +202,7 @@ impl<'a> LineGauge<'a> {
 
     pub fn ratio(mut self, ratio: f64) -> Self {
         assert!(
-            ratio <= 1.0 && ratio >= 0.0,
+            (0.0..=1.0).contains(&ratio),
             "Ratio should be between 0 and 1 inclusively."
         );
         self.ratio = ratio;
@@ -252,21 +234,15 @@ impl<'a> LineGauge<'a> {
 }
 
 impl<'a> Widget for LineGauge<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        buf.set_style(area, self.style);
         let gauge_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if gauge_area.height < 1 {
@@ -277,7 +253,7 @@ impl<'a> Widget for LineGauge<'a> {
         let label = self
             .label
             .unwrap_or_else(move || Spans::from(format!("{:.0}%", ratio * 100.0)));
-        let (col, row) = ctx.buffer.set_spans(
+        let (col, row) = buf.set_spans(
             gauge_area.left(),
             gauge_area.top(),
             &label,
@@ -291,8 +267,7 @@ impl<'a> Widget for LineGauge<'a> {
         let end = start
             + (f64::from(gauge_area.right().saturating_sub(start)) * self.ratio).floor() as u16;
         for col in start..end {
-            ctx.buffer
-                .get_mut(col, row)
+            buf.get_mut(col, row)
                 .set_symbol(self.line_set.horizontal)
                 .set_style(Style {
                     fg: self.gauge_style.fg,
@@ -302,8 +277,7 @@ impl<'a> Widget for LineGauge<'a> {
                 });
         }
         for col in end..gauge_area.right() {
-            ctx.buffer
-                .get_mut(col, row)
+            buf.get_mut(col, row)
                 .set_symbol(self.line_set.horizontal)
                 .set_style(Style {
                     fg: self.gauge_style.bg,

src/widgets/list.rs

@@ -1,20 +1,28 @@
 use crate::{
+    buffer::Buffer,
     layout::{Corner, Rect},
     style::Style,
     text::Text,
-    widgets::{Block, RenderContext, Widget},
+    widgets::{Block, StatefulWidget, Widget},
 };
-use std::iter::{self, Iterator};
 use unicode_width::UnicodeWidthStr;
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Default)]
 pub struct ListState {
     offset: usize,
+    selected: Option<usize>,
 }
 
-impl Default for ListState {
-    fn default() -> ListState {
-        ListState { offset: 0 }
+impl ListState {
+    pub fn selected(&self) -> Option<usize> {
+        self.selected
+    }
+
+    pub fn select(&mut self, index: Option<usize>) {
+        self.selected = index;
+        if index.is_none() {
+            self.offset = 0;
+        }
     }
 }
 
@@ -70,7 +78,8 @@ pub struct List<'a> {
     highlight_style: Style,
     /// Symbol in front of the selected item (Shift all items to the right)
     highlight_symbol: Option<&'a str>,
-    selected: Option<usize>,
+    /// Whether to repeat the highlight symbol for each line of the selected item
+    repeat_highlight_symbol: bool,
 }
 
 impl<'a> List<'a> {
@@ -85,7 +94,7 @@ impl<'a> List<'a> {
             start_corner: Corner::TopLeft,
             highlight_style: Style::default(),
             highlight_symbol: None,
-            selected: None,
+            repeat_highlight_symbol: false,
         }
     }
 
@@ -109,33 +118,67 @@ impl<'a> List<'a> {
         self
     }
 
+    pub fn repeat_highlight_symbol(mut self, repeat: bool) -> List<'a> {
+        self.repeat_highlight_symbol = repeat;
+        self
+    }
+
     pub fn start_corner(mut self, corner: Corner) -> List<'a> {
         self.start_corner = corner;
         self
     }
 
-    pub fn select(mut self, index: Option<usize>) -> List<'a> {
-        self.selected = index;
-        self
+    fn get_items_bounds(
+        &self,
+        selected: Option<usize>,
+        offset: usize,
+        max_height: usize,
+    ) -> (usize, usize) {
+        let offset = offset.min(self.items.len().saturating_sub(1));
+        let mut start = offset;
+        let mut end = offset;
+        let mut height = 0;
+        for item in self.items.iter().skip(offset) {
+            if height + item.height() > max_height {
+                break;
+            }
+            height += item.height();
+            end += 1;
+        }
+
+        let selected = selected.unwrap_or(0).min(self.items.len() - 1);
+        while selected >= end {
+            height = height.saturating_add(self.items[end].height());
+            end += 1;
+            while height > max_height {
+                height = height.saturating_sub(self.items[start].height());
+                start += 1;
+            }
+        }
+        while selected < start {
+            start -= 1;
+            height = height.saturating_add(self.items[start].height());
+            while height > max_height {
+                end -= 1;
+                height = height.saturating_sub(self.items[end].height());
+            }
+        }
+        (start, end)
     }
 }
 
-impl<'a> Widget for List<'a> {
+impl<'a> StatefulWidget for List<'a> {
     type State = ListState;
 
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+        buf.set_style(area, self.style);
         let list_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if list_area.width < 1 || list_area.height < 1 {
@@ -147,52 +190,19 @@ impl<'a> Widget for List<'a> {
         }
         let list_height = list_area.height as usize;
 
-        if self.selected.is_none() {
-            ctx.state.offset = 0;
-        }
-
-        let mut start = ctx.state.offset;
-        let mut end = ctx.state.offset;
-        let mut height = 0;
-        for item in self.items.iter().skip(ctx.state.offset) {
-            if height + item.height() > list_height {
-                break;
-            }
-            height += item.height();
-            end += 1;
-        }
-
-        let selected = self.selected.unwrap_or(0).min(self.items.len() - 1);
-        while selected >= end {
-            height = height.saturating_add(self.items[end].height());
-            end += 1;
-            while height > list_height {
-                height = height.saturating_sub(self.items[start].height());
-                start += 1;
-            }
-        }
-        while selected < start {
-            start -= 1;
-            height = height.saturating_add(self.items[start].height());
-            while height > list_height {
-                end -= 1;
-                height = height.saturating_sub(self.items[end].height());
-            }
-        }
-        ctx.state.offset = start;
+        let (start, end) = self.get_items_bounds(state.selected, state.offset, list_height);
+        state.offset = start;
 
         let highlight_symbol = self.highlight_symbol.unwrap_or("");
-        let blank_symbol = iter::repeat(" ")
-            .take(highlight_symbol.width())
-            .collect::<String>();
+        let blank_symbol = " ".repeat(highlight_symbol.width());
 
         let mut current_height = 0;
-        let has_selection = self.selected.is_some();
+        let has_selection = state.selected.is_some();
         for (i, item) in self
             .items
             .iter_mut()
             .enumerate()
-            .skip(ctx.state.offset)
+            .skip(state.offset)
             .take(end - start)
         {
             let (x, y) = match self.start_corner {
@@ -213,30 +223,42 @@ impl<'a> Widget for List<'a> {
                 height: item.height() as u16,
             };
             let item_style = self.style.patch(item.style);
-            ctx.buffer.set_style(area, item_style);
+            buf.set_style(area, item_style);
 
-            let is_selected = self.selected.map(|s| s == i).unwrap_or(false);
-            let elem_x = if has_selection {
-                let symbol = if is_selected {
+            let is_selected = state.selected.map(|s| s == i).unwrap_or(false);
+            for (j, line) in item.content.lines.iter().enumerate() {
+                // if the item is selected, we need to display the hightlight symbol:
+                // - either for the first line of the item only,
+                // - or for each line of the item if the appropriate option is set
+                let symbol = if is_selected && (j == 0 || self.repeat_highlight_symbol) {
                     highlight_symbol
                 } else {
                     &blank_symbol
                 };
-                let (x, _) =
-                    ctx.buffer
-                        .set_stringn(x, y, symbol, list_area.width as usize, item_style);
-                x
-            } else {
-                x
-            };
-            let max_element_width = (list_area.width - (elem_x - x)) as usize;
-            for (j, line) in item.content.lines.iter().enumerate() {
-                ctx.buffer
-                    .set_spans(elem_x, y + j as u16, line, max_element_width as u16);
+                let (elem_x, max_element_width) = if has_selection {
+                    let (elem_x, _) = buf.set_stringn(
+                        x,
+                        y + j as u16,
+                        symbol,
+                        list_area.width as usize,
+                        item_style,
+                    );
+                    (elem_x, (list_area.width - (elem_x - x)) as u16)
+                } else {
+                    (x, list_area.width)
+                };
+                buf.set_spans(elem_x, y + j as u16, line, max_element_width as u16);
             }
             if is_selected {
-                ctx.buffer.set_style(area, self.highlight_style);
+                buf.set_style(area, self.highlight_style);
             }
         }
     }
 }
+
+impl<'a> Widget for List<'a> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let mut state = ListState::default();
+        StatefulWidget::render(self, area, buf, &mut state);
+    }
+}

src/widgets/mod.rs

@@ -1,4 +1,4 @@
-//! `widgets` is a collection of types that implement [`Widget`].
+//! `widgets` is a collection of types that implement [`Widget`] or [`StatefulWidget`] or both.
 //!
 //! All widgets are implemented using the builder pattern and are consumable objects. They are not
 //! meant to be stored but used as *commands* to draw common figures in the UI.
@@ -62,30 +62,123 @@ bitflags! {
 
 /// Base requirements for a Widget
 pub trait Widget {
-    /// State stores everything that need to be saved between draw calls in order for the widget to
-    /// implement certain UI patterns.
-    ///
-    /// For example, the [`List`] widget can highlight the item currently selected. This can be
-    /// translated in an offset, which is the number of elements to skip in order to have the
-    /// selected item within the viewport currently allocated to this widget. If the widget had
-    /// only access to the index of the selected item, it could only implement the following
-    /// behavior: whenever the selected item is out of the viewport scroll to a predefined position
-    /// (making the selected item the last viewable item or the one in the middle for example).
-    /// Nonetheless, if the widget has access to the last computed offset then it can implement a
-    /// natural scrolling experience where the last offset is reused until the selected item is out
-    /// of the viewport.
-    type State;
-    /// Render the widget in the internal buffer. That the only method required to implement a
-    /// custom widget.
-    fn render(self, ctx: &mut RenderContext<Self::State>);
+    /// Draws the current state of the widget in the given buffer. That is the only method required
+    /// to implement a custom widget.
+    fn render(self, area: Rect, buf: &mut Buffer);
 }
 
-/// RenderContext is a set of dependencies that may be used when a widget is rendered.
-pub struct RenderContext<'a, S> {
-    /// Area where the widget is rendered.
-    pub area: Rect,
-    /// Buffer where the drawing operations will be temporarily registered.
-    pub buffer: &'a mut Buffer,
-    /// Internal state associated with the widget.
-    pub state: &'a mut S,
+/// A `StatefulWidget` is a widget that can take advantage of some local state to remember things
+/// between two draw calls.
+///
+/// Most widgets can be drawn directly based on the input parameters. However, some features may
+/// require some kind of associated state to be implemented.
+///
+/// For example, the [`List`] widget can highlight the item currently selected. This can be
+/// translated in an offset, which is the number of elements to skip in order to have the selected
+/// item within the viewport currently allocated to this widget. The widget can therefore only
+/// provide the following behavior: whenever the selected item is out of the viewport scroll to a
+/// predefined position (making the selected item the last viewable item or the one in the middle
+/// for example). Nonetheless, if the widget has access to the last computed offset then it can
+/// implement a natural scrolling experience where the last offset is reused until the selected
+/// item is out of the viewport.
+///
+/// ## Examples
+///
+/// ```rust,no_run
+/// # use std::io;
+/// # use tui::Terminal;
+/// # use tui::backend::{Backend, TestBackend};
+/// # use tui::widgets::{Widget, List, ListItem, ListState};
+///
+/// // Let's say we have some events to display.
+/// struct Events {
+///     // `items` is the state managed by your application.
+///     items: Vec<String>,
+///     // `state` is the state that can be modified by the UI. It stores the index of the selected
+///     // item as well as the offset computed during the previous draw call (used to implement
+///     // natural scrolling).
+///     state: ListState
+/// }
+///
+/// impl Events {
+///     fn new(items: Vec<String>) -> Events {
+///         Events {
+///             items,
+///             state: ListState::default(),
+///         }
+///     }
+///
+///     pub fn set_items(&mut self, items: Vec<String>) {
+///         self.items = items;
+///         // We reset the state as the associated items have changed. This effectively reset
+///         // the selection as well as the stored offset.
+///         self.state = ListState::default();
+///     }
+///
+///     // Select the next item. This will not be reflected until the widget is drawn in the
+///     // `Terminal::draw` callback using `Frame::render_stateful_widget`.
+///     pub fn next(&mut self) {
+///         let i = match self.state.selected() {
+///             Some(i) => {
+///                 if i >= self.items.len() - 1 {
+///                     0
+///                 } else {
+///                     i + 1
+///                 }
+///             }
+///             None => 0,
+///         };
+///         self.state.select(Some(i));
+///     }
+///
+///     // Select the previous item. This will not be reflected until the widget is drawn in the
+///     // `Terminal::draw` callback using `Frame::render_stateful_widget`.
+///     pub fn previous(&mut self) {
+///         let i = match self.state.selected() {
+///             Some(i) => {
+///                 if i == 0 {
+///                     self.items.len() - 1
+///                 } else {
+///                     i - 1
+///                 }
+///             }
+///             None => 0,
+///         };
+///         self.state.select(Some(i));
+///     }
+///
+///     // Unselect the currently selected item if any. The implementation of `ListState` makes
+///     // sure that the stored offset is also reset.
+///     pub fn unselect(&mut self) {
+///         self.state.select(None);
+///     }
+/// }
+///
+/// # let backend = TestBackend::new(5, 5);
+/// # let mut terminal = Terminal::new(backend).unwrap();
+///
+/// let mut events = Events::new(vec![
+///     String::from("Item 1"),
+///     String::from("Item 2")
+/// ]);
+///
+/// loop {
+///     terminal.draw(|f| {
+///         // The items managed by the application are transformed to something
+///         // that is understood by tui.
+///         let items: Vec<ListItem>= events.items.iter().map(|i| ListItem::new(i.as_ref())).collect();
+///         // The `List` widget is then built with those items.
+///         let list = List::new(items);
+///         // Finally the widget is rendered using the associated state. `events.state` is
+///         // effectively the only thing that we will "remember" from this draw call.
+///         f.render_stateful_widget(list, f.size(), &mut events.state);
+///     });
+///
+///     // In response to some input events or an external http request or whatever:
+///     events.next();
+/// }
+/// ```
+pub trait StatefulWidget {
+    type State;
+    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
 }

src/widgets/paragraph.rs

@@ -1,10 +1,11 @@
 use crate::{
-    layout::Alignment,
+    buffer::Buffer,
+    layout::{Alignment, Rect},
     style::Style,
     text::{StyledGrapheme, Text},
     widgets::{
         reflow::{LineComposer, LineTruncator, WordWrapper},
-        Block, RenderContext, Widget,
+        Block, Widget,
     },
 };
 use std::iter;
@@ -39,7 +40,7 @@ fn get_line_offset(line_width: u16, text_area_width: u16, alignment: Alignment)
 ///     .block(Block::default().title("Paragraph").borders(Borders::ALL))
 ///     .style(Style::default().fg(Color::White).bg(Color::Black))
 ///     .alignment(Alignment::Center)
-///     .wrap(Wrap { trim: true });
+///     .wrap(Wrap { trim: true, break_words: false });
 /// ```
 #[derive(Debug, Clone)]
 pub struct Paragraph<'a> {
@@ -69,7 +70,7 @@ pub struct Paragraph<'a> {
 ///     - Here is another point that is long enough to wrap"#);
 ///
 /// // With leading spaces trimmed (window width of 30 chars):
-/// Paragraph::new(bullet_points.clone()).wrap(Wrap { trim: true });
+/// Paragraph::new(bullet_points.clone()).wrap(Wrap { trim: true, break_words: false });
 /// // Some indented points:
 /// // - First thing goes here and is
 /// // long so that it wraps
@@ -77,7 +78,7 @@ pub struct Paragraph<'a> {
 /// // is long enough to wrap
 ///
 /// // But without trimming, indentation is preserved:
-/// Paragraph::new(bullet_points).wrap(Wrap { trim: false });
+/// Paragraph::new(bullet_points).wrap(Wrap { trim: false, break_words: false });
 /// // Some indented points:
 /// //     - First thing goes here
 /// // and is long so that it wraps
@@ -88,6 +89,8 @@ pub struct Paragraph<'a> {
 pub struct Wrap {
     /// Should leading whitespace be trimmed
     pub trim: bool,
+    /// Should words at the end of lines be broken
+    pub break_words: bool,
 }
 
 impl<'a> Paragraph<'a> {
@@ -132,21 +135,15 @@ impl<'a> Paragraph<'a> {
 }
 
 impl<'a> Widget for Paragraph<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        buf.set_style(area, self.style);
         let text_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if text_area.height < 1 {
@@ -167,22 +164,27 @@ impl<'a> Widget for Paragraph<'a> {
                 }))
         });
 
-        let mut line_composer: Box<dyn LineComposer> = if let Some(Wrap { trim }) = self.wrap {
-            Box::new(WordWrapper::new(&mut styled, text_area.width, trim))
-        } else {
-            let mut line_composer = Box::new(LineTruncator::new(&mut styled, text_area.width));
-            if let Alignment::Left = self.alignment {
-                line_composer.set_horizontal_offset(self.scroll.1);
-            }
-            line_composer
-        };
+        let mut line_composer: Box<dyn LineComposer> =
+            if let Some(Wrap { trim, break_words }) = self.wrap {
+                Box::new(WordWrapper::new(
+                    &mut styled,
+                    text_area.width,
+                    trim,
+                    break_words,
+                ))
+            } else {
+                let mut line_composer = Box::new(LineTruncator::new(&mut styled, text_area.width));
+                if let Alignment::Left = self.alignment {
+                    line_composer.set_horizontal_offset(self.scroll.1);
+                }
+                line_composer
+            };
         let mut y = 0;
         while let Some((current_line, current_line_width)) = line_composer.next_line() {
             if y >= self.scroll.0 {
                 let mut x = get_line_offset(current_line_width, text_area.width, self.alignment);
                 for StyledGrapheme { symbol, style } in current_line {
-                    ctx.buffer
-                        .get_mut(text_area.left() + x, text_area.top() + y - self.scroll.0)
+                    buf.get_mut(text_area.left() + x, text_area.top() + y - self.scroll.0)
                         .set_symbol(if symbol.is_empty() {
                             // If the symbol is empty, the last char which rendered last time will
                             // leave on the line. It's a quick fix.

src/widgets/reflow.rs

@@ -19,6 +19,7 @@ pub struct WordWrapper<'a, 'b> {
     next_line: Vec<StyledGrapheme<'a>>,
     /// Removes the leading whitespace from lines
     trim: bool,
+    break_words: bool,
 }
 
 impl<'a, 'b> WordWrapper<'a, 'b> {
@@ -26,6 +27,7 @@ impl<'a, 'b> WordWrapper<'a, 'b> {
         symbols: &'b mut dyn Iterator<Item = StyledGrapheme<'a>>,
         max_line_width: u16,
         trim: bool,
+        break_words: bool,
     ) -> WordWrapper<'a, 'b> {
         WordWrapper {
             symbols,
@@ -33,6 +35,7 @@ impl<'a, 'b> WordWrapper<'a, 'b> {
             current_line: vec![],
             next_line: vec![],
             trim,
+            break_words,
         }
     }
 }
@@ -87,11 +90,12 @@ impl<'a, 'b> LineComposer<'a> for WordWrapper<'a, 'b> {
 
             if current_line_width > self.max_line_width {
                 // If there was no word break in the text, wrap at the end of the line.
-                let (truncate_at, truncated_width) = if symbols_to_last_word_end != 0 {
-                    (symbols_to_last_word_end, width_to_last_word_end)
-                } else {
-                    (self.current_line.len() - 1, self.max_line_width)
-                };
+                let (truncate_at, truncated_width) =
+                    if symbols_to_last_word_end != 0 && !self.break_words {
+                        (symbols_to_last_word_end, width_to_last_word_end)
+                    } else {
+                        (self.current_line.len() - 1, self.max_line_width)
+                    };
 
                 // Push the remainder to the next line but strip leading whitespace:
                 {
@@ -235,7 +239,7 @@ mod test {
     use unicode_segmentation::UnicodeSegmentation;
 
     enum Composer {
-        WordWrapper { trim: bool },
+        WordWrapper { trim: bool, break_words: bool },
         LineTruncator,
     }
 
@@ -244,9 +248,12 @@ mod test {
         let mut styled =
             UnicodeSegmentation::graphemes(text, true).map(|g| StyledGrapheme { symbol: g, style });
         let mut composer: Box<dyn LineComposer> = match which {
-            Composer::WordWrapper { trim } => {
-                Box::new(WordWrapper::new(&mut styled, text_area_width, trim))
-            }
+            Composer::WordWrapper { trim, break_words } => Box::new(WordWrapper::new(
+                &mut styled,
+                text_area_width,
+                trim,
+                break_words,
+            )),
             Composer::LineTruncator => Box::new(LineTruncator::new(&mut styled, text_area_width)),
         };
         let mut lines = vec![];
@@ -268,8 +275,14 @@ mod test {
         let width = 40;
         for i in 1..width {
             let text = "a".repeat(i);
-            let (word_wrapper, _) =
-                run_composer(Composer::WordWrapper { trim: true }, &text, width as u16);
+            let (word_wrapper, _) = run_composer(
+                Composer::WordWrapper {
+                    trim: true,
+                    break_words: true,
+                },
+                &text,
+                width as u16,
+            );
             let (line_truncator, _) = run_composer(Composer::LineTruncator, &text, width as u16);
             let expected = vec![text];
             assert_eq!(word_wrapper, expected);
@@ -282,7 +295,14 @@ mod test {
         let width = 20;
         let text =
             "abcdefg\nhijklmno\npabcdefg\nhijklmn\nopabcdefghijk\nlmnopabcd\n\n\nefghijklmno";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
 
         let wrapped: Vec<&str> = text.split('\n').collect();
@@ -294,8 +314,14 @@ mod test {
     fn line_composer_long_word() {
         let width = 20;
         let text = "abcdefghijklmnopabcdefghijklmnopabcdefghijklmnopabcdefghijklmno";
-        let (word_wrapper, _) =
-            run_composer(Composer::WordWrapper { trim: true }, text, width as u16);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width as u16,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width as u16);
 
         let wrapped = vec![
@@ -320,10 +346,19 @@ mod test {
         let text_multi_space =
             "abcd efghij    klmnopabcd efgh     ijklmnopabcdefg hijkl mnopab c d e f g h i j k l \
              m n o";
-        let (word_wrapper_single_space, _) =
-            run_composer(Composer::WordWrapper { trim: true }, text, width as u16);
+        let (word_wrapper_single_space, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width as u16,
+        );
         let (word_wrapper_multi_space, _) = run_composer(
-            Composer::WordWrapper { trim: true },
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
             text_multi_space,
             width as u16,
         );
@@ -346,7 +381,14 @@ mod test {
     fn line_composer_zero_width() {
         let width = 0;
         let text = "abcd efghij klmnopabcd efgh ijklmnopabcdefg hijkl mnopab ";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
 
         let expected: Vec<&str> = Vec::new();
@@ -358,7 +400,14 @@ mod test {
     fn line_composer_max_line_width_of_1() {
         let width = 1;
         let text = "abcd efghij klmnopabcd efgh ijklmnopabcdefg hijkl mnopab ";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
 
         let expected: Vec<&str> = UnicodeSegmentation::graphemes(text, true)
@@ -373,7 +422,14 @@ mod test {
         let width = 1;
         let text = "コンピュータ上で文字を扱う場合、典型的には文字\naaaによる通信を行う場合にその\
                     両端点では、";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
         assert_eq!(word_wrapper, vec!["", "a", "a", "a"]);
         assert_eq!(line_truncator, vec!["", "a"]);
@@ -384,7 +440,14 @@ mod test {
     fn line_composer_word_wrapper_mixed_length() {
         let width = 20;
         let text = "abcd efghij klmnopabcdefghijklmnopabcdefghijkl mnopab cdefghi j klmno";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(
             word_wrapper,
             vec![
@@ -402,9 +465,15 @@ mod test {
         let width = 20;
         let text = "コンピュータ上で文字を扱う場合、典型的には文字による通信を行う場合にその両端点\
                     では、";
-        let (word_wrapper, word_wrapper_width) =
-            run_composer(Composer::WordWrapper { trim: true }, &text, width);
-        let (line_truncator, _) = run_composer(Composer::LineTruncator, &text, width);
+        let (word_wrapper, word_wrapper_width) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
+        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
         assert_eq!(line_truncator, vec!["コンピュータ上で文字"]);
         let wrapped = vec![
             "コンピュータ上で文字",
@@ -421,7 +490,14 @@ mod test {
     fn line_composer_leading_whitespace_removal() {
         let width = 20;
         let text = "AAAAAAAAAAAAAAAAAAAA    AAA";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
         assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAAAAAAA", "AAA",]);
         assert_eq!(line_truncator, vec!["AAAAAAAAAAAAAAAAAAAA"]);
@@ -432,7 +508,14 @@ mod test {
     fn line_composer_lots_of_spaces() {
         let width = 20;
         let text = "                                                                     ";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
         assert_eq!(word_wrapper, vec![""]);
         assert_eq!(line_truncator, vec!["                    "]);
@@ -444,7 +527,14 @@ mod test {
     fn line_composer_char_plus_lots_of_spaces() {
         let width = 20;
         let text = "a                                                                     ";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
         // What's happening below is: the first line gets consumed, trailing spaces discarded,
         // after 20 of which a word break occurs (probably shouldn't). The second line break
@@ -463,8 +553,14 @@ mod test {
         // hiragana and katakana...
         // This happens to also be a test case for mixed width because regular spaces are single width.
         let text = "コンピュ ータ上で文字を扱う場合、 典型的には文 字による 通信を行 う場合にその両端点では、";
-        let (word_wrapper, word_wrapper_width) =
-            run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, word_wrapper_width) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(
             word_wrapper,
             vec![
@@ -485,13 +581,26 @@ mod test {
     fn line_composer_word_wrapper_nbsp() {
         let width = 20;
         let text = "AAAAAAAAAAAAAAA AAAA\u{00a0}AAA";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAA", "AAAA\u{00a0}AAA",]);
 
         // Ensure that if the character was a regular space, it would be wrapped differently.
-        let text_space = text.replace("\u{00a0}", " ");
-        let (word_wrapper_space, _) =
-            run_composer(Composer::WordWrapper { trim: true }, &text_space, width);
+        let text_space = text.replace('\u{00a0}', " ");
+        let (word_wrapper_space, _) = run_composer(
+            Composer::WordWrapper {
+                trim: true,
+                break_words: true,
+            },
+            &text_space,
+            width,
+        );
         assert_eq!(word_wrapper_space, vec!["AAAAAAAAAAAAAAA AAAA", "AAA",]);
     }
 
@@ -499,7 +608,14 @@ mod test {
     fn line_composer_word_wrapper_preserve_indentation() {
         let width = 20;
         let text = "AAAAAAAAAAAAAAAAAAAA    AAA";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: false,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAAAAAAA", "   AAA",]);
     }
 
@@ -507,7 +623,14 @@ mod test {
     fn line_composer_word_wrapper_preserve_indentation_with_wrap() {
         let width = 10;
         let text = "AAA AAA AAAAA AA AAAAAA\n B\n  C\n   D";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: false,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(
             word_wrapper,
             vec!["AAA AAA", "AAAAA AA", "AAAAAA", " B", "  C", "   D"]
@@ -518,7 +641,14 @@ mod test {
     fn line_composer_word_wrapper_preserve_indentation_lots_of_whitespace() {
         let width = 10;
         let text = "               4 Indent\n                 must wrap!";
-        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
+        let (word_wrapper, _) = run_composer(
+            Composer::WordWrapper {
+                trim: false,
+                break_words: true,
+            },
+            text,
+            width,
+        );
         assert_eq!(
             word_wrapper,
             vec![

src/widgets/sparkline.rs

@@ -1,7 +1,9 @@
 use crate::{
+    buffer::Buffer,
+    layout::Rect,
     style::Style,
     symbols,
-    widgets::{Block, RenderContext, Widget},
+    widgets::{Block, Widget},
 };
 use std::cmp::min;
 
@@ -73,20 +75,14 @@ impl<'a> Sparkline<'a> {
 }
 
 impl<'a> Widget for Sparkline<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
         let spark_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if spark_area.height < 1 {
@@ -123,8 +119,7 @@ impl<'a> Widget for Sparkline<'a> {
                     7 => self.bar_set.seven_eighths,
                     _ => self.bar_set.full,
                 };
-                ctx.buffer
-                    .get_mut(spark_area.left() + i as u16, spark_area.top() + j)
+                buf.get_mut(spark_area.left() + i as u16, spark_area.top() + j)
                     .set_symbol(symbol)
                     .set_style(self.style);
 
@@ -140,23 +135,14 @@ impl<'a> Widget for Sparkline<'a> {
 
 #[cfg(test)]
 mod tests {
-    use crate::{
-        buffer::Buffer,
-        layout::Rect,
-        widgets::{RenderContext, Sparkline, Widget},
-    };
+    use super::*;
 
     #[test]
     fn it_does_not_panic_if_max_is_zero() {
         let widget = Sparkline::default().data(&[0, 0, 0]);
         let area = Rect::new(0, 0, 3, 1);
         let mut buffer = Buffer::empty(area);
-        let mut ctx = RenderContext {
-            area,
-            buffer: &mut buffer,
-            state: &mut (),
-        };
-        widget.render(&mut ctx);
+        widget.render(area, &mut buffer);
     }
 
     #[test]
@@ -164,11 +150,6 @@ mod tests {
         let widget = Sparkline::default().data(&[0, 1, 2]).max(0);
         let area = Rect::new(0, 0, 3, 1);
         let mut buffer = Buffer::empty(area);
-        let mut ctx = RenderContext {
-            area,
-            buffer: &mut buffer,
-            state: &mut (),
-        };
-        widget.render(&mut ctx);
+        widget.render(area, &mut buffer);
     }
 }

src/widgets/table.rs

@@ -1,18 +1,9 @@
 use crate::{
     buffer::Buffer,
-    layout::{Constraint, Rect},
+    layout::{Constraint, Direction, Layout, Rect},
     style::Style,
     text::Text,
-    widgets::{Block, RenderContext, Widget},
-};
-use cassowary::{
-    strength::{MEDIUM, REQUIRED, WEAK},
-    WeightedRelation::*,
-    {Expression, Solver},
-};
-use std::{
-    collections::HashMap,
-    iter::{self, Iterator},
+    widgets::{Block, StatefulWidget, Widget},
 };
 use unicode_width::UnicodeWidthStr;
 
@@ -23,6 +14,7 @@ use unicode_width::UnicodeWidthStr;
 /// # use tui::widgets::Cell;
 /// # use tui::style::{Style, Modifier};
 /// # use tui::text::{Span, Spans, Text};
+/// # use std::borrow::Cow;
 /// Cell::from("simple string");
 ///
 /// Cell::from(Span::from("span"));
@@ -33,6 +25,8 @@ use unicode_width::UnicodeWidthStr;
 /// ]));
 ///
 /// Cell::from(Text::from("a text"));
+///
+/// Cell::from(Text::from(Cow::Borrowed("hello")));
 /// ```
 ///
 /// You can apply a [`Style`] on the entire [`Cell`] using [`Cell::style`] or rely on the styling
@@ -81,6 +75,16 @@ where
 /// ]);
 /// ```
 ///
+/// You can also construct a row from any type that can be converted into [`Text`]:
+/// ```rust
+/// # use std::borrow::Cow;
+/// # use tui::widgets::Row;
+/// Row::new(vec![
+///     Cow::Borrowed("hello"),
+///     Cow::Owned("world".to_uppercase()),
+/// ]);
+/// ```
+///
 /// By default, a row has a height of 1 but you can change this using [`Row::height`].
 #[derive(Debug, Clone, PartialEq, Default)]
 pub struct Row<'a> {
@@ -200,7 +204,6 @@ pub struct Table<'a> {
     header: Option<Row<'a>>,
     /// Data to display in each row
     rows: Vec<Row<'a>>,
-    selected: Option<usize>,
 }
 
 impl<'a> Table<'a> {
@@ -217,7 +220,6 @@ impl<'a> Table<'a> {
             highlight_symbol: None,
             header: None,
             rows: rows.into_iter().collect(),
-            selected: None,
         }
     }
 
@@ -264,78 +266,43 @@ impl<'a> Table<'a> {
         self
     }
 
-    pub fn select(mut self, index: Option<usize>) -> Self {
-        self.selected = index;
-        self
-    }
-
     fn get_columns_widths(&self, max_width: u16, has_selection: bool) -> Vec<u16> {
-        let mut solver = Solver::new();
-        let mut var_indices = HashMap::new();
-        let mut ccs = Vec::new();
-        let mut variables = Vec::new();
-        for i in 0..self.widths.len() {
-            let var = cassowary::Variable::new();
-            variables.push(var);
-            var_indices.insert(var, i);
-        }
-        let spacing_width = (variables.len() as u16).saturating_sub(1) * self.column_spacing;
-        let mut available_width = max_width.saturating_sub(spacing_width);
+        let mut constraints = Vec::with_capacity(self.widths.len() * 2 + 1);
         if has_selection {
             let highlight_symbol_width =
                 self.highlight_symbol.map(|s| s.width() as u16).unwrap_or(0);
-            available_width = available_width.saturating_sub(highlight_symbol_width);
+            constraints.push(Constraint::Length(highlight_symbol_width));
         }
-        for (i, constraint) in self.widths.iter().enumerate() {
-            ccs.push(variables[i] | GE(WEAK) | 0.);
-            ccs.push(match *constraint {
-                Constraint::Length(v) => variables[i] | EQ(MEDIUM) | f64::from(v),
-                Constraint::Percentage(v) => {
-                    variables[i] | EQ(WEAK) | (f64::from(v * available_width) / 100.0)
-                }
-                Constraint::Ratio(n, d) => {
-                    variables[i]
-                        | EQ(WEAK)
-                        | (f64::from(available_width) * f64::from(n) / f64::from(d))
-                }
-                Constraint::Min(v) => variables[i] | GE(WEAK) | f64::from(v),
-                Constraint::Max(v) => variables[i] | LE(WEAK) | f64::from(v),
-            })
+        for constraint in self.widths {
+            constraints.push(*constraint);
+            constraints.push(Constraint::Length(self.column_spacing));
         }
-        solver
-            .add_constraint(
-                variables
-                    .iter()
-                    .fold(Expression::from_constant(0.), |acc, v| acc + *v)
-                    | LE(REQUIRED)
-                    | f64::from(available_width),
-            )
-            .unwrap();
-        solver.add_constraints(&ccs).unwrap();
-        let mut widths = vec![0; variables.len()];
-        for &(var, value) in solver.fetch_changes() {
-            let index = var_indices[&var];
-            let value = if value.is_sign_negative() {
-                0
-            } else {
-                value.round() as u16
-            };
-            widths[index] = value;
+        if !self.widths.is_empty() {
+            constraints.pop();
         }
-        // Cassowary could still return columns widths greater than the max width when there are
-        // fixed length constraints that cannot be satisfied. Therefore, we clamp the widths from
-        // left to right.
-        let mut available_width = max_width;
-        for w in &mut widths {
-            *w = available_width.min(*w);
-            available_width = available_width
-                .saturating_sub(*w)
-                .saturating_sub(self.column_spacing);
+        let mut chunks = Layout::default()
+            .direction(Direction::Horizontal)
+            .constraints(constraints)
+            .expand_to_fill(false)
+            .split(Rect {
+                x: 0,
+                y: 0,
+                width: max_width,
+                height: 1,
+            });
+        if has_selection {
+            chunks.remove(0);
         }
-        widths
+        chunks.iter().step_by(2).map(|c| c.width).collect()
     }
 
-    fn get_row_bounds(&self, offset: usize, max_height: u16) -> (usize, usize) {
+    fn get_row_bounds(
+        &self,
+        selected: Option<usize>,
+        offset: usize,
+        max_height: u16,
+    ) -> (usize, usize) {
+        let offset = offset.min(self.rows.len().saturating_sub(1));
         let mut start = offset;
         let mut end = offset;
         let mut height = 0;
@@ -347,7 +314,7 @@ impl<'a> Table<'a> {
             end += 1;
         }
 
-        let selected = self.selected.unwrap_or(0).min(self.rows.len() - 1);
+        let selected = selected.unwrap_or(0).min(self.rows.len() - 1);
         while selected >= end {
             height = height.saturating_add(self.rows[end].total_height());
             end += 1;
@@ -368,54 +335,53 @@ impl<'a> Table<'a> {
     }
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Default)]
 pub struct TableState {
     offset: usize,
+    selected: Option<usize>,
 }
 
-impl Default for TableState {
-    fn default() -> TableState {
-        TableState { offset: 0 }
+impl TableState {
+    pub fn selected(&self) -> Option<usize> {
+        self.selected
+    }
+
+    pub fn select(&mut self, index: Option<usize>) {
+        self.selected = index;
+        if index.is_none() {
+            self.offset = 0;
+        }
     }
 }
 
-impl<'a> Widget for Table<'a> {
+impl<'a> StatefulWidget for Table<'a> {
     type State = TableState;
 
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        if ctx.area.area() == 0 {
+    fn render(mut self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+        if area.area() == 0 {
             return;
         }
-        ctx.buffer.set_style(ctx.area, self.style);
+        buf.set_style(area, self.style);
         let table_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
-        let has_selection = self.selected.is_some();
-        if !has_selection {
-            ctx.state.offset = 0;
-        }
+        let has_selection = state.selected.is_some();
         let columns_widths = self.get_columns_widths(table_area.width, has_selection);
         let highlight_symbol = self.highlight_symbol.unwrap_or("");
-        let blank_symbol = iter::repeat(" ")
-            .take(highlight_symbol.width())
-            .collect::<String>();
+        let blank_symbol = " ".repeat(highlight_symbol.width());
         let mut current_height = 0;
         let mut rows_height = table_area.height;
 
         // Draw header
         if let Some(ref header) = self.header {
             let max_header_height = table_area.height.min(header.total_height());
-            ctx.buffer.set_style(
+            buf.set_style(
                 Rect {
                     x: table_area.left(),
                     y: table_area.top(),
@@ -430,7 +396,7 @@ impl<'a> Widget for Table<'a> {
             }
             for (width, cell) in columns_widths.iter().zip(header.cells.iter()) {
                 render_cell(
-                    ctx.buffer,
+                    buf,
                     cell,
                     Rect {
                         x: col,
@@ -449,13 +415,13 @@ impl<'a> Widget for Table<'a> {
         if self.rows.is_empty() {
             return;
         }
-        let (start, end) = self.get_row_bounds(ctx.state.offset, rows_height);
-        ctx.state.offset = start;
+        let (start, end) = self.get_row_bounds(state.selected, state.offset, rows_height);
+        state.offset = start;
         for (i, table_row) in self
             .rows
             .iter_mut()
             .enumerate()
-            .skip(ctx.state.offset)
+            .skip(state.offset)
             .take(end - start)
         {
             let (row, col) = (table_area.top() + current_height, table_area.left());
@@ -466,21 +432,16 @@ impl<'a> Widget for Table<'a> {
                 width: table_area.width,
                 height: table_row.height,
             };
-            ctx.buffer.set_style(table_row_area, table_row.style);
-            let is_selected = self.selected.map(|s| s == i).unwrap_or(false);
+            buf.set_style(table_row_area, table_row.style);
+            let is_selected = state.selected.map(|s| s == i).unwrap_or(false);
             let table_row_start_col = if has_selection {
                 let symbol = if is_selected {
                     highlight_symbol
                 } else {
                     &blank_symbol
                 };
-                let (col, _) = ctx.buffer.set_stringn(
-                    col,
-                    row,
-                    symbol,
-                    table_area.width as usize,
-                    table_row.style,
-                );
+                let (col, _) =
+                    buf.set_stringn(col, row, symbol, table_area.width as usize, table_row.style);
                 col
             } else {
                 col
@@ -488,7 +449,7 @@ impl<'a> Widget for Table<'a> {
             let mut col = table_row_start_col;
             for (width, cell) in columns_widths.iter().zip(table_row.cells.iter()) {
                 render_cell(
-                    ctx.buffer,
+                    buf,
                     cell,
                     Rect {
                         x: col,
@@ -500,7 +461,7 @@ impl<'a> Widget for Table<'a> {
                 col += *width + self.column_spacing;
             }
             if is_selected {
-                ctx.buffer.set_style(table_row_area, self.highlight_style);
+                buf.set_style(table_row_area, self.highlight_style);
             }
         }
     }
@@ -516,6 +477,13 @@ fn render_cell(buf: &mut Buffer, cell: &Cell, area: Rect) {
     }
 }
 
+impl<'a> Widget for Table<'a> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let mut state = TableState::default();
+        StatefulWidget::render(self, area, buf, &mut state);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/widgets/tabs.rs

@@ -1,9 +1,10 @@
 use crate::{
+    buffer::Buffer,
     layout::Rect,
     style::Style,
     symbols,
     text::{Span, Spans},
-    widgets::{Block, RenderContext, Widget},
+    widgets::{Block, Widget},
 };
 
 /// A widget to display available tabs in a multiple panels context.
@@ -80,21 +81,15 @@ impl<'a> Tabs<'a> {
 }
 
 impl<'a> Widget for Tabs<'a> {
-    type State = ();
-
-    fn render(mut self, ctx: &mut RenderContext<Self::State>) {
-        ctx.buffer.set_style(ctx.area, self.style);
+    fn render(mut self, area: Rect, buf: &mut Buffer) {
+        buf.set_style(area, self.style);
         let tabs_area = match self.block.take() {
             Some(b) => {
-                let inner_area = b.inner(ctx.area);
-                b.render(&mut RenderContext {
-                    area: ctx.area,
-                    buffer: ctx.buffer,
-                    state: &mut (),
-                });
+                let inner_area = b.inner(area);
+                b.render(area, buf);
                 inner_area
             }
-            None => ctx.area,
+            None => area,
         };
 
         if tabs_area.height < 1 {
@@ -110,11 +105,9 @@ impl<'a> Widget for Tabs<'a> {
             if remaining_width == 0 {
                 break;
             }
-            let pos = ctx
-                .buffer
-                .set_spans(x, tabs_area.top(), &title, remaining_width);
+            let pos = buf.set_spans(x, tabs_area.top(), &title, remaining_width);
             if i == self.selected {
-                ctx.buffer.set_style(
+                buf.set_style(
                     Rect {
                         x,
                         y: tabs_area.top(),
@@ -129,9 +122,7 @@ impl<'a> Widget for Tabs<'a> {
             if remaining_width == 0 || last_title {
                 break;
             }
-            let pos = ctx
-                .buffer
-                .set_span(x, tabs_area.top(), &self.divider, remaining_width);
+            let pos = buf.set_span(x, tabs_area.top(), &self.divider, remaining_width);
             x = pos.0;
         }
     }

tests/widgets_block.rs

@@ -1,7 +1,7 @@
 use tui::{
     backend::TestBackend,
     buffer::Buffer,
-    layout::Rect,
+    layout::{Alignment, Rect},
     style::{Color, Style},
     text::Span,
     widgets::{Block, Borders},
@@ -211,3 +211,136 @@ fn widgets_block_renders_on_small_areas() {
         Buffer::with_lines(vec!["┌Test─"]),
     );
 }
+
+#[test]
+fn widgets_block_title_alignment() {
+    let test_case = |alignment, borders, expected| {
+        let backend = TestBackend::new(15, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        let block = Block::default()
+            .title(Span::styled("Title", Style::default()))
+            .title_alignment(alignment)
+            .borders(borders);
+
+        let area = Rect {
+            x: 1,
+            y: 0,
+            width: 13,
+            height: 2,
+        };
+
+        terminal
+            .draw(|f| {
+                f.render_widget(block, area);
+            })
+            .unwrap();
+
+        terminal.backend().assert_buffer(&expected);
+    };
+
+    // title top-left with all borders
+    test_case(
+        Alignment::Left,
+        Borders::ALL,
+        Buffer::with_lines(vec![" ┌Title──────┐ ", " └───────────┘ "]),
+    );
+
+    // title top-left without top border
+    test_case(
+        Alignment::Left,
+        Borders::LEFT | Borders::BOTTOM | Borders::RIGHT,
+        Buffer::with_lines(vec![" │Title      │ ", " └───────────┘ "]),
+    );
+
+    // title top-left with no left border
+    test_case(
+        Alignment::Left,
+        Borders::TOP | Borders::RIGHT | Borders::BOTTOM,
+        Buffer::with_lines(vec![" Title───────┐ ", " ────────────┘ "]),
+    );
+
+    // title top-left without right border
+    test_case(
+        Alignment::Left,
+        Borders::LEFT | Borders::TOP | Borders::BOTTOM,
+        Buffer::with_lines(vec![" ┌Title─────── ", " └──────────── "]),
+    );
+
+    // title top-left without borders
+    test_case(
+        Alignment::Left,
+        Borders::NONE,
+        Buffer::with_lines(vec![" Title         ", "               "]),
+    );
+
+    // title center with all borders
+    test_case(
+        Alignment::Center,
+        Borders::ALL,
+        Buffer::with_lines(vec![" ┌───Title───┐ ", " └───────────┘ "]),
+    );
+
+    // title center without top border
+    test_case(
+        Alignment::Center,
+        Borders::LEFT | Borders::BOTTOM | Borders::RIGHT,
+        Buffer::with_lines(vec![" │   Title   │ ", " └───────────┘ "]),
+    );
+
+    // title center with no left border
+    test_case(
+        Alignment::Center,
+        Borders::TOP | Borders::RIGHT | Borders::BOTTOM,
+        Buffer::with_lines(vec![" ────Title───┐ ", " ────────────┘ "]),
+    );
+
+    // title center without right border
+    test_case(
+        Alignment::Center,
+        Borders::LEFT | Borders::TOP | Borders::BOTTOM,
+        Buffer::with_lines(vec![" ┌───Title──── ", " └──────────── "]),
+    );
+
+    // title center without borders
+    test_case(
+        Alignment::Center,
+        Borders::NONE,
+        Buffer::with_lines(vec!["     Title     ", "               "]),
+    );
+
+    // title top-right with all borders
+    test_case(
+        Alignment::Right,
+        Borders::ALL,
+        Buffer::with_lines(vec![" ┌──────Title┐ ", " └───────────┘ "]),
+    );
+
+    // title top-right without top border
+    test_case(
+        Alignment::Right,
+        Borders::LEFT | Borders::BOTTOM | Borders::RIGHT,
+        Buffer::with_lines(vec![" │      Title│ ", " └───────────┘ "]),
+    );
+
+    // title top-right with no left border
+    test_case(
+        Alignment::Right,
+        Borders::TOP | Borders::RIGHT | Borders::BOTTOM,
+        Buffer::with_lines(vec![" ───────Title┐ ", " ────────────┘ "]),
+    );
+
+    // title top-right without right border
+    test_case(
+        Alignment::Right,
+        Borders::LEFT | Borders::TOP | Borders::BOTTOM,
+        Buffer::with_lines(vec![" ┌───────Title ", " └──────────── "]),
+    );
+
+    // title top-right without borders
+    test_case(
+        Alignment::Right,
+        Borders::NONE,
+        Buffer::with_lines(vec!["         Title ", "               "]),
+    );
+}

tests/widgets_canvas.rs

@@ -0,0 +1,42 @@
+use tui::{
+    backend::TestBackend,
+    buffer::Buffer,
+    style::{Color, Style},
+    text::Span,
+    widgets::canvas::Canvas,
+    Terminal,
+};
+
+#[test]
+fn widgets_canvas_draw_labels() {
+    let backend = TestBackend::new(5, 5);
+    let mut terminal = Terminal::new(backend).unwrap();
+    terminal
+        .draw(|f| {
+            let label = String::from("test");
+            let canvas = Canvas::default()
+                .background_color(Color::Yellow)
+                .x_bounds([0.0, 5.0])
+                .y_bounds([0.0, 5.0])
+                .paint(|ctx| {
+                    ctx.print(
+                        0.0,
+                        0.0,
+                        Span::styled(label.clone(), Style::default().fg(Color::Blue)),
+                    );
+                });
+            f.render_widget(canvas, f.size());
+        })
+        .unwrap();
+
+    let mut expected = Buffer::with_lines(vec!["    ", "    ", "     ", "     ", "test "]);
+    for row in 0..5 {
+        for col in 0..5 {
+            expected.get_mut(col, row).set_bg(Color::Yellow);
+        }
+    }
+    for col in 0..4 {
+        expected.get_mut(col, 4).set_fg(Color::Blue);
+    }
+    terminal.backend().assert_buffer(&expected)
+}

tests/widgets_chart.rs

@@ -1,3 +1,4 @@
+use tui::layout::Alignment;
 use tui::{
     backend::TestBackend,
     buffer::Buffer,
@@ -13,6 +14,22 @@ fn create_labels<'a>(labels: &'a [&'a str]) -> Vec<Span<'a>> {
     labels.iter().map(|l| Span::from(*l)).collect()
 }
 
+fn axis_test_case<S>(width: u16, height: u16, x_axis: Axis, y_axis: Axis, lines: Vec<S>)
+where
+    S: AsRef<str>,
+{
+    let backend = TestBackend::new(width, height);
+    let mut terminal = Terminal::new(backend).unwrap();
+    terminal
+        .draw(|f| {
+            let chart = Chart::new(vec![]).x_axis(x_axis).y_axis(y_axis);
+            f.render_widget(chart, f.size());
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(lines);
+    terminal.backend().assert_buffer(&expected);
+}
+
 #[test]
 fn widgets_chart_can_render_on_small_areas() {
     let test_case = |width, height| {
@@ -47,6 +64,197 @@ fn widgets_chart_can_render_on_small_areas() {
     test_case(2, 2);
 }
 
+#[test]
+fn widgets_chart_handles_long_labels() {
+    let test_case = |x_labels, y_labels, x_alignment, lines| {
+        let mut x_axis = Axis::default().bounds([0.0, 1.0]);
+        if let Some((left_label, right_label)) = x_labels {
+            x_axis = x_axis
+                .labels(vec![Span::from(left_label), Span::from(right_label)])
+                .labels_alignment(x_alignment);
+        }
+
+        let mut y_axis = Axis::default().bounds([0.0, 1.0]);
+        if let Some((left_label, right_label)) = y_labels {
+            y_axis = y_axis.labels(vec![Span::from(left_label), Span::from(right_label)]);
+        }
+
+        axis_test_case(10, 5, x_axis, y_axis, lines);
+    };
+
+    test_case(
+        Some(("AAAA", "B")),
+        None,
+        Alignment::Left,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            "   ───────",
+            "AAA      B",
+        ],
+    );
+    test_case(
+        Some(("A", "BBBB")),
+        None,
+        Alignment::Left,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            " ─────────",
+            "A     BBBB",
+        ],
+    );
+    test_case(
+        Some(("AAAAAAAAAAA", "B")),
+        None,
+        Alignment::Left,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            "   ───────",
+            "AAA      B",
+        ],
+    );
+    test_case(
+        Some(("A", "B")),
+        Some(("CCCCCCC", "D")),
+        Alignment::Left,
+        vec![
+            "D  │      ",
+            "   │      ",
+            "CCC│      ",
+            "   └──────",
+            "   A     B",
+        ],
+    );
+    test_case(
+        Some(("AAAAAAAAAA", "B")),
+        Some(("C", "D")),
+        Alignment::Center,
+        vec![
+            "D  │      ",
+            "   │      ",
+            "C  │      ",
+            "   └──────",
+            "AAAAAAA  B",
+        ],
+    );
+    test_case(
+        Some(("AAAAAAA", "B")),
+        Some(("C", "D")),
+        Alignment::Right,
+        vec![
+            "D│        ",
+            " │        ",
+            "C│        ",
+            " └────────",
+            " AAAAA   B",
+        ],
+    );
+    test_case(
+        Some(("AAAAAAA", "BBBBBBB")),
+        Some(("C", "D")),
+        Alignment::Right,
+        vec![
+            "D│        ",
+            " │        ",
+            "C│        ",
+            " └────────",
+            " AAAAABBBB",
+        ],
+    );
+}
+
+#[test]
+fn widgets_chart_handles_x_axis_labels_alignments() {
+    let test_case = |y_alignment, lines| {
+        let x_axis = Axis::default()
+            .labels(vec![Span::from("AAAA"), Span::from("B"), Span::from("C")])
+            .labels_alignment(y_alignment);
+
+        let y_axis = Axis::default();
+
+        axis_test_case(10, 5, x_axis, y_axis, lines);
+    };
+
+    test_case(
+        Alignment::Left,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            "   ───────",
+            "AAA   B  C",
+        ],
+    );
+    test_case(
+        Alignment::Center,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            "  ────────",
+            "AAAA B   C",
+        ],
+    );
+    test_case(
+        Alignment::Right,
+        vec![
+            "          ",
+            "          ",
+            "          ",
+            "──────────",
+            "AAA  B   C",
+        ],
+    );
+}
+
+#[test]
+fn widgets_chart_handles_y_axis_labels_alignments() {
+    let test_case = |y_alignment, lines| {
+        let x_axis = Axis::default().labels(create_labels(&["AAAAA", "B"]));
+
+        let y_axis = Axis::default()
+            .labels(create_labels(&["C", "D"]))
+            .labels_alignment(y_alignment);
+
+        axis_test_case(20, 5, x_axis, y_axis, lines);
+    };
+    test_case(
+        Alignment::Left,
+        vec![
+            "D   │               ",
+            "    │               ",
+            "C   │               ",
+            "    └───────────────",
+            "AAAAA              B",
+        ],
+    );
+    test_case(
+        Alignment::Center,
+        vec![
+            "  D │               ",
+            "    │               ",
+            "  C │               ",
+            "    └───────────────",
+            "AAAAA              B",
+        ],
+    );
+    test_case(
+        Alignment::Right,
+        vec![
+            "   D│               ",
+            "    │               ",
+            "   C│               ",
+            "    └───────────────",
+            "AAAAA              B",
+        ],
+    );
+}
+
 #[test]
 fn widgets_chart_can_have_axis_with_zero_length_bounds() {
     let backend = TestBackend::new(100, 100);
@@ -257,7 +465,7 @@ fn widgets_chart_can_have_a_legend() {
         "│    │ ••                                               •• │",
         "│0.0 │•                                              X Axis│",
         "│    └─────────────────────────────────────────────────────│",
-        "│  0.0                      50.0                     100.0 │",
+        "│  0.0                        50.0                    100.0│",
         "└──────────────────────────────────────────────────────────┘",
     ]);
 

tests/widgets_gauge.rs

@@ -2,8 +2,9 @@ use tui::{
     backend::TestBackend,
     buffer::Buffer,
     layout::{Constraint, Direction, Layout, Rect},
-    style::{Color, Style},
+    style::{Color, Modifier, Style},
     symbols,
+    text::Span,
     widgets::{Block, Borders, Gauge, LineGauge},
     Terminal,
 };
@@ -116,6 +117,89 @@ fn widgets_gauge_renders_no_unicode() {
     terminal.backend().assert_buffer(&expected);
 }
 
+#[test]
+fn widgets_gauge_applies_styles() {
+    let backend = TestBackend::new(12, 5);
+    let mut terminal = Terminal::new(backend).unwrap();
+
+    terminal
+        .draw(|f| {
+            let gauge = Gauge::default()
+                .block(
+                    Block::default()
+                        .title(Span::styled("Test", Style::default().fg(Color::Red)))
+                        .borders(Borders::ALL),
+                )
+                .gauge_style(Style::default().fg(Color::Blue).bg(Color::Red))
+                .percent(43)
+                .label(Span::styled(
+                    "43%",
+                    Style::default()
+                        .fg(Color::Green)
+                        .add_modifier(Modifier::BOLD),
+                ));
+            f.render_widget(gauge, f.size());
+        })
+        .unwrap();
+    let mut expected = Buffer::with_lines(vec![
+        "┌Test──────┐",
+        "│          │",
+        "│   43%    │",
+        "│          │",
+        "└──────────┘",
+    ]);
+    // title
+    expected.set_style(Rect::new(1, 0, 4, 1), Style::default().fg(Color::Red));
+    // gauge area
+    expected.set_style(
+        Rect::new(1, 1, 10, 3),
+        Style::default().fg(Color::Blue).bg(Color::Red),
+    );
+    // filled area
+    for y in 1..4 {
+        expected.set_style(
+            Rect::new(1, y, 4, 1),
+            // filled style is invert of gauge_style
+            Style::default().fg(Color::Red).bg(Color::Blue),
+        );
+    }
+    // label (foreground and modifier from label style)
+    expected.set_style(
+        Rect::new(4, 2, 1, 1),
+        Style::default()
+            .fg(Color::Green)
+            // "4" is in the filled area so background is gauge_style foreground
+            .bg(Color::Blue)
+            .add_modifier(Modifier::BOLD),
+    );
+    expected.set_style(
+        Rect::new(5, 2, 2, 1),
+        Style::default()
+            .fg(Color::Green)
+            // "3%" is not in the filled area so background is gauge_style background
+            .bg(Color::Red)
+            .add_modifier(Modifier::BOLD),
+    );
+    terminal.backend().assert_buffer(&expected);
+}
+
+#[test]
+fn widgets_gauge_supports_large_labels() {
+    let backend = TestBackend::new(10, 1);
+    let mut terminal = Terminal::new(backend).unwrap();
+
+    terminal
+        .draw(|f| {
+            let gauge = Gauge::default()
+                .percent(43)
+                .label("43333333333333333333333333333%");
+            f.render_widget(gauge, f.size());
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(vec!["4333333333"]);
+    terminal.backend().assert_buffer(&expected);
+}
+
 #[test]
 fn widgets_line_gauge_renders() {
     let backend = TestBackend::new(20, 4);

tests/widgets_list.rs

@@ -4,7 +4,8 @@ use tui::{
     layout::Rect,
     style::{Color, Style},
     symbols,
-    widgets::{Block, Borders, List, ListItem},
+    text::Spans,
+    widgets::{Block, Borders, List, ListItem, ListState},
     Terminal,
 };
 
@@ -12,6 +13,8 @@ use tui::{
 fn widgets_list_should_highlight_the_selected_item() {
     let backend = TestBackend::new(10, 3);
     let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = ListState::default();
+    state.select(Some(1));
     terminal
         .draw(|f| {
             let size = f.size();
@@ -21,10 +24,9 @@ fn widgets_list_should_highlight_the_selected_item() {
                 ListItem::new("Item 3"),
             ];
             let list = List::new(items)
-                .select(Some(1))
                 .highlight_style(Style::default().bg(Color::Yellow))
                 .highlight_symbol(">> ");
-            f.render_widget(list, size);
+            f.render_stateful_widget(list, size, &mut state);
         })
         .unwrap();
     let mut expected = Buffer::with_lines(vec!["   Item 1 ", ">> Item 2 ", "   Item 3 "]);
@@ -72,15 +74,127 @@ fn widgets_list_should_truncate_items() {
         },
     ];
     for case in cases {
+        let mut state = ListState::default();
+        state.select(case.selected);
         terminal
             .draw(|f| {
                 let list = List::new(case.items.clone())
                     .block(Block::default().borders(Borders::RIGHT))
-                    .select(case.selected)
                     .highlight_symbol(">> ");
-                f.render_widget(list, Rect::new(0, 0, 8, 2));
+                f.render_stateful_widget(list, Rect::new(0, 0, 8, 2), &mut state);
             })
             .unwrap();
         terminal.backend().assert_buffer(&case.expected);
     }
 }
+
+#[test]
+fn widgets_list_should_clamp_offset_if_items_are_removed() {
+    let backend = TestBackend::new(10, 4);
+    let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = ListState::default();
+
+    // render with 6 items => offset will be at 2
+    state.select(Some(5));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let items = vec![
+                ListItem::new("Item 0"),
+                ListItem::new("Item 1"),
+                ListItem::new("Item 2"),
+                ListItem::new("Item 3"),
+                ListItem::new("Item 4"),
+                ListItem::new("Item 5"),
+            ];
+            let list = List::new(items).highlight_symbol(">> ");
+            f.render_stateful_widget(list, size, &mut state);
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(vec!["   Item 2 ", "   Item 3 ", "   Item 4 ", ">> Item 5 "]);
+    terminal.backend().assert_buffer(&expected);
+
+    // render again with 1 items => check offset is clamped to 1
+    state.select(Some(1));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let items = vec![ListItem::new("Item 3")];
+            let list = List::new(items).highlight_symbol(">> ");
+            f.render_stateful_widget(list, size, &mut state);
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(vec!["   Item 3 ", "          ", "          ", "          "]);
+    terminal.backend().assert_buffer(&expected);
+}
+
+#[test]
+fn widgets_list_should_display_multiline_items() {
+    let backend = TestBackend::new(10, 6);
+    let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = ListState::default();
+    state.select(Some(1));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let items = vec![
+                ListItem::new(vec![Spans::from("Item 1"), Spans::from("Item 1a")]),
+                ListItem::new(vec![Spans::from("Item 2"), Spans::from("Item 2b")]),
+                ListItem::new(vec![Spans::from("Item 3"), Spans::from("Item 3c")]),
+            ];
+            let list = List::new(items)
+                .highlight_style(Style::default().bg(Color::Yellow))
+                .highlight_symbol(">> ");
+            f.render_stateful_widget(list, size, &mut state);
+        })
+        .unwrap();
+    let mut expected = Buffer::with_lines(vec![
+        "   Item 1 ",
+        "   Item 1a",
+        ">> Item 2 ",
+        "   Item 2b",
+        "   Item 3 ",
+        "   Item 3c",
+    ]);
+    for x in 0..10 {
+        expected.get_mut(x, 2).set_bg(Color::Yellow);
+        expected.get_mut(x, 3).set_bg(Color::Yellow);
+    }
+    terminal.backend().assert_buffer(&expected);
+}
+
+#[test]
+fn widgets_list_should_repeat_highlight_symbol() {
+    let backend = TestBackend::new(10, 6);
+    let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = ListState::default();
+    state.select(Some(1));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let items = vec![
+                ListItem::new(vec![Spans::from("Item 1"), Spans::from("Item 1a")]),
+                ListItem::new(vec![Spans::from("Item 2"), Spans::from("Item 2b")]),
+                ListItem::new(vec![Spans::from("Item 3"), Spans::from("Item 3c")]),
+            ];
+            let list = List::new(items)
+                .highlight_style(Style::default().bg(Color::Yellow))
+                .highlight_symbol(">> ")
+                .repeat_highlight_symbol(true);
+            f.render_stateful_widget(list, size, &mut state);
+        })
+        .unwrap();
+    let mut expected = Buffer::with_lines(vec![
+        "   Item 1 ",
+        "   Item 1a",
+        ">> Item 2 ",
+        ">> Item 2b",
+        "   Item 3 ",
+        "   Item 3c",
+    ]);
+    for x in 0..10 {
+        expected.get_mut(x, 2).set_bg(Color::Yellow);
+        expected.get_mut(x, 3).set_bg(Color::Yellow);
+    }
+    terminal.backend().assert_buffer(&expected);
+}

tests/widgets_paragraph.rs

@@ -25,7 +25,10 @@ fn widgets_paragraph_can_wrap_its_content() {
                 let paragraph = Paragraph::new(text)
                     .block(Block::default().borders(Borders::ALL))
                     .alignment(alignment)
-                    .wrap(Wrap { trim: true });
+                    .wrap(Wrap {
+                        trim: true,
+                        break_words: false,
+                    });
                 f.render_widget(paragraph, size);
             })
             .unwrap();
@@ -79,6 +82,76 @@ fn widgets_paragraph_can_wrap_its_content() {
     );
 }
 
+#[test]
+fn widgets_paragraph_can_wrap_its_content_with_word_break_enabled() {
+    let test_case = |alignment, expected| {
+        let backend = TestBackend::new(20, 10);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal
+            .draw(|f| {
+                let size = f.size();
+                let text = vec![Spans::from(SAMPLE_STRING)];
+                let paragraph = Paragraph::new(text)
+                    .block(Block::default().borders(Borders::ALL))
+                    .alignment(alignment)
+                    .wrap(Wrap {
+                        trim: true,
+                        break_words: true,
+                    });
+                f.render_widget(paragraph, size);
+            })
+            .unwrap();
+        terminal.backend().assert_buffer(&expected);
+    };
+
+    test_case(
+        Alignment::Left,
+        Buffer::with_lines(vec![
+            "┌──────────────────┐",
+            "│The library is bas│",
+            "│ed on the principl│",
+            "│e of immediate ren│",
+            "│dering with interm│",
+            "│ediate buffers. Th│",
+            "│is means that at e│",
+            "│ach new frame you │",
+            "│should build all w│",
+            "└──────────────────┘",
+        ]),
+    );
+    test_case(
+        Alignment::Right,
+        Buffer::with_lines(vec![
+            "┌──────────────────┐",
+            "│The library is bas│",
+            "│ed on the principl│",
+            "│e of immediate ren│",
+            "│dering with interm│",
+            "│ediate buffers. Th│",
+            "│is means that at e│",
+            "│ach new frame you │",
+            "│should build all w│",
+            "└──────────────────┘",
+        ]),
+    );
+    test_case(
+        Alignment::Center,
+        Buffer::with_lines(vec![
+            "┌──────────────────┐",
+            "│The library is bas│",
+            "│ed on the principl│",
+            "│e of immediate ren│",
+            "│dering with interm│",
+            "│ediate buffers. Th│",
+            "│is means that at e│",
+            "│ach new frame you │",
+            "│should build all w│",
+            "└──────────────────┘",
+        ]),
+    );
+}
+
 #[test]
 fn widgets_paragraph_renders_double_width_graphemes() {
     let backend = TestBackend::new(10, 10);
@@ -91,7 +164,10 @@ fn widgets_paragraph_renders_double_width_graphemes() {
             let text = vec![Spans::from(s)];
             let paragraph = Paragraph::new(text)
                 .block(Block::default().borders(Borders::ALL))
-                .wrap(Wrap { trim: true });
+                .wrap(Wrap {
+                    trim: true,
+                    break_words: false,
+                });
             f.render_widget(paragraph, size);
         })
         .unwrap();
@@ -123,7 +199,10 @@ fn widgets_paragraph_renders_mixed_width_graphemes() {
             let text = vec![Spans::from(s)];
             let paragraph = Paragraph::new(text)
                 .block(Block::default().borders(Borders::ALL))
-                .wrap(Wrap { trim: true });
+                .wrap(Wrap {
+                    trim: true,
+                    break_words: false,
+                });
             f.render_widget(paragraph, size);
         })
         .unwrap();

tests/widgets_table.rs

@@ -4,7 +4,7 @@ use tui::{
     layout::Constraint,
     style::{Color, Modifier, Style},
     text::{Span, Spans},
-    widgets::{Block, Borders, Cell, Row, Table},
+    widgets::{Block, Borders, Cell, Row, Table, TableState},
     Terminal,
 };
 
@@ -354,12 +354,12 @@ fn widgets_table_columns_widths_can_use_mixed_constraints() {
         ],
         Buffer::with_lines(vec![
             "┌────────────────────────────┐",
-            "│Hea Head2                Hea│",
+            "│Hea Head2                He │",
             "│                            │",
-            "│Row Row12                Row│",
-            "│Row Row22                Row│",
-            "│Row Row32                Row│",
-            "│Row Row42                Row│",
+            "│Row Row12                Ro │",
+            "│Row Row22                Ro │",
+            "│Row Row32                Ro │",
+            "│Row Row42                Ro │",
             "│                            │",
             "│                            │",
             "└────────────────────────────┘",
@@ -517,7 +517,7 @@ fn widgets_table_columns_widths_can_use_ratio_constraints() {
 
 #[test]
 fn widgets_table_can_have_rows_with_multi_lines() {
-    let test_case = |selected: Option<usize>, expected: Buffer| {
+    let test_case = |state: &mut TableState, expected: Buffer| {
         let backend = TestBackend::new(30, 8);
         let mut terminal = Terminal::new(backend).unwrap();
         terminal
@@ -537,17 +537,17 @@ fn widgets_table_can_have_rows_with_multi_lines() {
                     Constraint::Length(5),
                     Constraint::Length(5),
                 ])
-                .select(selected)
                 .column_spacing(1);
-                f.render_widget(table, size);
+                f.render_stateful_widget(table, size, state);
             })
             .unwrap();
         terminal.backend().assert_buffer(&expected);
     };
 
+    let mut state = TableState::default();
     // no selection
     test_case(
-        None,
+        &mut state,
         Buffer::with_lines(vec![
             "┌────────────────────────────┐",
             "│Head1 Head2 Head3           │",
@@ -561,8 +561,9 @@ fn widgets_table_can_have_rows_with_multi_lines() {
     );
 
     // select first
+    state.select(Some(0));
     test_case(
-        Some(0),
+        &mut state,
         Buffer::with_lines(vec![
             "┌────────────────────────────┐",
             "│   Head1 Head2 Head3        │",
@@ -576,8 +577,9 @@ fn widgets_table_can_have_rows_with_multi_lines() {
     );
 
     // select second (we don't show partially the 4th row)
+    state.select(Some(1));
     test_case(
-        Some(1),
+        &mut state,
         Buffer::with_lines(vec![
             "┌────────────────────────────┐",
             "│   Head1 Head2 Head3        │",
@@ -591,8 +593,9 @@ fn widgets_table_can_have_rows_with_multi_lines() {
     );
 
     // select 4th (we don't show partially the 1st row)
+    state.select(Some(3));
     test_case(
-        Some(3),
+        &mut state,
         Buffer::with_lines(vec![
             "┌────────────────────────────┐",
             "│   Head1 Head2 Head3        │",
@@ -610,6 +613,8 @@ fn widgets_table_can_have_rows_with_multi_lines() {
 fn widgets_table_can_have_elements_styled_individually() {
     let backend = TestBackend::new(30, 4);
     let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = TableState::default();
+    state.select(Some(0));
     terminal
         .draw(|f| {
             let size = f.size();
@@ -635,9 +640,8 @@ fn widgets_table_can_have_elements_styled_individually() {
                 Constraint::Length(6),
                 Constraint::Length(6),
             ])
-            .select(Some(0))
             .column_spacing(1);
-            f.render_widget(table, size);
+            f.render_stateful_widget(table, size, &mut state);
         })
         .unwrap();
 
@@ -711,3 +715,109 @@ fn widgets_table_should_render_even_if_empty() {
 
     terminal.backend().assert_buffer(&expected);
 }
+
+#[test]
+fn widgets_table_columns_dont_panic() {
+    let test_case = |state: &mut TableState, table: Table, width: u16| {
+        let backend = TestBackend::new(width, 8);
+        let mut terminal = Terminal::new(backend).unwrap();
+        terminal
+            .draw(|f| {
+                let size = f.size();
+                f.render_stateful_widget(table, size, state);
+            })
+            .unwrap();
+    };
+
+    // based on https://github.com/fdehau/tui-rs/issues/470#issuecomment-852562848
+    let table1_width = 98;
+    let table1 = Table::new(vec![Row::new(vec!["r1", "r2", "r3", "r4"])])
+        .header(Row::new(vec!["h1", "h2", "h3", "h4"]))
+        .block(Block::default().borders(Borders::ALL))
+        .highlight_symbol(">> ")
+        .column_spacing(1)
+        .widths(&[
+            Constraint::Percentage(15),
+            Constraint::Percentage(15),
+            Constraint::Percentage(25),
+            Constraint::Percentage(45),
+        ]);
+
+    let mut state = TableState::default();
+
+    // select first, which would cause a panic before fix
+    state.select(Some(0));
+    test_case(&mut state, table1.clone(), table1_width);
+}
+
+#[test]
+fn widgets_table_should_clamp_offset_if_rows_are_removed() {
+    let backend = TestBackend::new(30, 8);
+    let mut terminal = Terminal::new(backend).unwrap();
+    let mut state = TableState::default();
+
+    // render with 6 items => offset will be at 2
+    state.select(Some(5));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let table = Table::new(vec![
+                Row::new(vec!["Row01", "Row02", "Row03"]),
+                Row::new(vec!["Row11", "Row12", "Row13"]),
+                Row::new(vec!["Row21", "Row22", "Row23"]),
+                Row::new(vec!["Row31", "Row32", "Row33"]),
+                Row::new(vec!["Row41", "Row42", "Row43"]),
+                Row::new(vec!["Row51", "Row52", "Row53"]),
+            ])
+            .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
+            .block(Block::default().borders(Borders::ALL))
+            .widths(&[
+                Constraint::Length(5),
+                Constraint::Length(5),
+                Constraint::Length(5),
+            ])
+            .column_spacing(1);
+            f.render_stateful_widget(table, size, &mut state);
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(vec![
+        "┌────────────────────────────┐",
+        "│Head1 Head2 Head3           │",
+        "│                            │",
+        "│Row21 Row22 Row23           │",
+        "│Row31 Row32 Row33           │",
+        "│Row41 Row42 Row43           │",
+        "│Row51 Row52 Row53           │",
+        "└────────────────────────────┘",
+    ]);
+    terminal.backend().assert_buffer(&expected);
+
+    // render with 1 item => offset will be at 1
+    state.select(Some(1));
+    terminal
+        .draw(|f| {
+            let size = f.size();
+            let table = Table::new(vec![Row::new(vec!["Row31", "Row32", "Row33"])])
+                .header(Row::new(vec!["Head1", "Head2", "Head3"]).bottom_margin(1))
+                .block(Block::default().borders(Borders::ALL))
+                .widths(&[
+                    Constraint::Length(5),
+                    Constraint::Length(5),
+                    Constraint::Length(5),
+                ])
+                .column_spacing(1);
+            f.render_stateful_widget(table, size, &mut state);
+        })
+        .unwrap();
+    let expected = Buffer::with_lines(vec![
+        "┌────────────────────────────┐",
+        "│Head1 Head2 Head3           │",
+        "│                            │",
+        "│Row31 Row32 Row33           │",
+        "│                            │",
+        "│                            │",
+        "│                            │",
+        "└────────────────────────────┘",
+    ]);
+    terminal.backend().assert_buffer(&expected);
+}