feat!(terminal): inline viewport

2021-12-26 13:41:17 +01:00
20 changed files with 701 additions and 613 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ on:
 name: CI

 env:
-  CI_CARGO_MAKE_VERSION: 0.35.8
+  CI_CARGO_MAKE_VERSION: 0.35.6

 jobs:
  linux:
@@ -17,8 +17,10 @@ jobs:
    runs-on: ubuntu-latest
    strategy:
      matrix:
-        rust: ["1.56.1", "stable"]
+        rust: ["1.52.1", "stable"]
    steps:
+      - name: "Install dependencies"
+        run: sudo apt-get install libncurses5-dev
      - uses: hecrj/setup-rust-action@967aec96c6a27a0ce15c1dac3aaba332d60565e2
        with:
          rust-version: ${{ matrix.rust }}
@@ -45,7 +47,7 @@ jobs:
    runs-on: windows-latest
    strategy:
      matrix:
-        rust: ["1.56.1", "stable"]
+        rust: ["1.52.1", "stable"]
    steps:
      - uses: actions/checkout@v1
      - uses: hecrj/setup-rust-action@967aec96c6a27a0ce15c1dac3aaba332d60565e2
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,52 +2,9 @@

 ## 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

--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,18 +1,18 @@
 [package]
 name = "tui"
-version = "0.18.0"
+version = "0.16.0"
 authors = ["Florian Dehau <work@fdehau.com>"]
 description = """
 A library to build rich terminal user interfaces or dashboards
 """
-documentation = "https://docs.rs/tui/0.18.0/tui/"
+documentation = "https://docs.rs/tui/0.16.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 = "2021"
+edition = "2018"

 [badges]

@@ -20,15 +20,17 @@ edition = "2021"
 default = ["crossterm"]

 [dependencies]
+tracing = "0.1"
 bitflags = "1.3"
 cassowary = "0.3"
 unicode-segmentation = "1.2"
 unicode-width = "0.1"
 termion = { version = "1.5", optional = true }
-crossterm = { version = "0.23", optional = true }
+crossterm = { version = "0.22", optional = true }
 serde = { version = "1", optional = true, features = ["derive"]}

 [dev-dependencies]
+tracing-subscriber = "0.2"
 rand = "0.8"
 argh = "0.1"

@@ -64,10 +66,6 @@ required-features = ["crossterm"]
 name = "list"
 required-features = ["crossterm"]

-[[example]]
-name = "panic"
-required-features = ["crossterm"]
-
 [[example]]
 name = "paragraph"
 required-features = ["crossterm"]
@@ -91,3 +89,7 @@ required-features = ["crossterm"]
 [[example]]
 name = "user_input"
 required-features = ["crossterm"]
+
+[[example]]
+name = "inline"
+required-features = ["crossterm"]
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ you may rely on the previously cited libraries to achieve such features.

 ### Rust version requirements

-Since version 0.17.0, `tui` requires **rustc version 1.56.1 or greater**.
+Since version 0.17.0, `tui` requires **rustc version 1.52.1 or greater**.

 ### [Documentation](https://docs.rs/tui)

@@ -45,8 +45,8 @@ cargo run --example demo --no-default-features --features=termion --release -- -

 where `tick-rate` is the UI refresh rate in ms.

-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).
+The UI code is in [examples/demo/ui.rs](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/demo/ui.rs) while the
+application state is in [examples/demo/app.rs](https://github.com/fdehau/tui-rs/blob/v0.16.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:
@@ -59,16 +59,16 @@ cargo run --example demo --release -- --tick-rate 200 --enhanced-graphics false

 The library comes with the following list of widgets:

-  * [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)
+  * [Block](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/block.rs)
+  * [Gauge](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/gauge.rs)
+  * [Sparkline](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/sparkline.rs)
+  * [Chart](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/chart.rs)
+  * [BarChart](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/barchart.rs)
+  * [List](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/list.rs)
+  * [Table](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/table.rs)
+  * [Paragraph](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/paragraph.rs)
+  * [Canvas (with line, point cloud, map)](https://github.com/fdehau/tui-rs/blob/v0.16.0/examples/canvas.rs)
+  * [Tabs](https://github.com/fdehau/tui-rs/blob/v0.16.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 gauge example `cargo run --example gauge`), and quit by pressing `q`.
@@ -108,13 +108,6 @@ You can run all examples by running `cargo make run-examples` (require
 * [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

--- a/examples/demo/ui.rs
+++ b/examples/demo/ui.rs
@@ -293,10 +293,7 @@ where
            .fg(Color::Magenta)
            .add_modifier(Modifier::BOLD),
    ));
-    let paragraph = Paragraph::new(text).block(block).wrap(Wrap {
-        trim: true,
-        break_words: false,
-    });
+    let paragraph = Paragraph::new(text).block(block).wrap(Wrap { trim: true });
    f.render_widget(paragraph, area);
 }

--- a/examples/inline.rs
+++ b/examples/inline.rs
@@ -0,0 +1,311 @@
+use rand::distributions::{Distribution, Uniform};
+use std::{
+    collections::{BTreeMap, VecDeque},
+    error::Error,
+    io,
+    sync::mpsc,
+    thread,
+    time::{Duration, Instant},
+};
+use tracing::{event, span, Level};
+use tui::{
+    backend::{Backend, CrosstermBackend},
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    symbols,
+    text::{Span, Spans},
+    widgets::{Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget},
+    Frame, Terminal, TerminalOptions, ViewportVariant,
+};
+
+const NUM_DOWNLOADS: usize = 10;
+
+type DownloadId = usize;
+type WorkerId = usize;
+
+enum Event {
+    Input(crossterm::event::KeyEvent),
+    Tick,
+    Resize,
+    DownloadUpdate(WorkerId, DownloadId, f64),
+    DownloadDone(WorkerId, DownloadId),
+}
+
+struct Downloads {
+    pending: VecDeque<Download>,
+    in_progress: BTreeMap<WorkerId, DownloadInProgress>,
+}
+
+impl Downloads {
+    fn next(&mut self, worker_id: WorkerId) -> Option<Download> {
+        match self.pending.pop_front() {
+            Some(d) => {
+                self.in_progress.insert(
+                    worker_id,
+                    DownloadInProgress {
+                        id: d.id,
+                        started_at: Instant::now(),
+                        progress: 0.0,
+                    },
+                );
+                Some(d)
+            }
+            None => None,
+        }
+    }
+}
+
+struct DownloadInProgress {
+    id: DownloadId,
+    started_at: Instant,
+    progress: f64,
+}
+
+struct Download {
+    id: DownloadId,
+    size: usize,
+}
+
+struct Worker {
+    id: WorkerId,
+    tx: mpsc::Sender<Download>,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+        .with_writer(io::stderr)
+        .init();
+
+    crossterm::terminal::enable_raw_mode()?;
+    let stdout = io::stdout();
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::with_options(
+        backend,
+        TerminalOptions {
+            viewport: ViewportVariant::Inline(8),
+        },
+    )?;
+
+    let (tx, rx) = mpsc::channel();
+    input_handling(tx.clone());
+    let workers = workers(tx);
+    let mut downloads = downloads();
+
+    for w in &workers {
+        let d = downloads.next(w.id).unwrap();
+        w.tx.send(d).unwrap();
+    }
+
+    run_app(&mut terminal, workers, downloads, rx)?;
+
+    crossterm::terminal::disable_raw_mode()?;
+    terminal.clear()?;
+
+    Ok(())
+}
+
+fn input_handling(tx: mpsc::Sender<Event>) {
+    let tick_rate = Duration::from_millis(200);
+    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 crossterm::event::poll(timeout).unwrap() {
+                match crossterm::event::read().unwrap() {
+                    crossterm::event::Event::Key(key) => tx.send(Event::Input(key)).unwrap(),
+                    crossterm::event::Event::Resize(_, _) => tx.send(Event::Resize).unwrap(),
+                    _ => {}
+                };
+            }
+            if last_tick.elapsed() >= tick_rate {
+                tx.send(Event::Tick).unwrap();
+                last_tick = Instant::now();
+            }
+        }
+    });
+}
+
+fn workers(tx: mpsc::Sender<Event>) -> Vec<Worker> {
+    (0..4)
+        .map(|id| {
+            let (worker_tx, worker_rx) = mpsc::channel::<Download>();
+            let tx = tx.clone();
+            thread::spawn(move || {
+                while let Ok(download) = worker_rx.recv() {
+                    let mut remaining = download.size;
+                    while remaining > 0 {
+                        let wait = (remaining as u64).min(10);
+                        thread::sleep(Duration::from_millis(wait * 10));
+                        remaining = remaining.saturating_sub(10);
+                        let progress = (download.size - remaining) * 100 / download.size;
+                        tx.send(Event::DownloadUpdate(id, download.id, progress as f64))
+                            .unwrap();
+                    }
+                    tx.send(Event::DownloadDone(id, download.id)).unwrap();
+                }
+            });
+            Worker { id, tx: worker_tx }
+        })
+        .collect()
+}
+
+fn downloads() -> Downloads {
+    let distribution = Uniform::new(0, 1000);
+    let mut rng = rand::thread_rng();
+    let pending = (0..NUM_DOWNLOADS)
+        .map(|id| {
+            let size = distribution.sample(&mut rng);
+            Download { id, size }
+        })
+        .collect();
+    Downloads {
+        pending,
+        in_progress: BTreeMap::new(),
+    }
+}
+
+fn run_app<B: Backend>(
+    terminal: &mut Terminal<B>,
+    workers: Vec<Worker>,
+    mut downloads: Downloads,
+    rx: mpsc::Receiver<Event>,
+) -> Result<(), Box<dyn Error>> {
+    let mut redraw = true;
+    loop {
+        if redraw {
+            terminal.draw(|f| ui(f, &downloads))?;
+        }
+        redraw = true;
+
+        let span = span!(Level::INFO, "recv");
+        let _guard = span.enter();
+        match rx.recv()? {
+            Event::Input(event) => {
+                if event.code == crossterm::event::KeyCode::Char('q') {
+                    break;
+                }
+            }
+            Event::Resize => {
+                event!(Level::INFO, "resize");
+                terminal.resize()?;
+            }
+            Event::Tick => {
+                event!(Level::INFO, "tick");
+            }
+            Event::DownloadUpdate(worker_id, download_id, progress) => {
+                event!(
+                    Level::INFO,
+                    worker_id,
+                    download_id,
+                    progress,
+                    "download update"
+                );
+                let download = downloads.in_progress.get_mut(&worker_id).unwrap();
+                download.progress = progress;
+                redraw = false
+            }
+            Event::DownloadDone(worker_id, download_id) => {
+                event!(Level::INFO, worker_id, download_id, "download done");
+                let download = downloads.in_progress.remove(&worker_id).unwrap();
+                terminal.insert_before(1, |buf| {
+                    Paragraph::new(Spans::from(vec![
+                        Span::from("Finished "),
+                        Span::styled(
+                            format!("download {}", download_id),
+                            Style::default().add_modifier(Modifier::BOLD),
+                        ),
+                        Span::from(format!(
+                            " in {}ms",
+                            download.started_at.elapsed().as_millis()
+                        )),
+                    ]))
+                    .render(buf.area, buf);
+                })?;
+                match downloads.next(worker_id) {
+                    Some(d) => workers[worker_id].tx.send(d).unwrap(),
+                    None => {
+                        if downloads.in_progress.is_empty() {
+                            terminal.insert_before(1, |buf| {
+                                Paragraph::new("Done !").render(buf.area, buf);
+                            })?;
+                            break;
+                        }
+                    }
+                };
+            }
+        };
+    }
+    Ok(())
+}
+
+fn ui<B: Backend>(f: &mut Frame<B>, downloads: &Downloads) {
+    let size = f.size();
+
+    let block = Block::default()
+        .title("Progress")
+        .title_alignment(Alignment::Center);
+    f.render_widget(block, size);
+
+    let chunks = Layout::default()
+        .constraints(vec![Constraint::Length(2), Constraint::Length(4)])
+        .margin(1)
+        .split(size);
+
+    // total progress
+    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
+    let progress = LineGauge::default()
+        .gauge_style(Style::default().fg(Color::Blue))
+        .label(format!("{}/{}", done, NUM_DOWNLOADS))
+        .ratio(done as f64 / NUM_DOWNLOADS as f64);
+    f.render_widget(progress, chunks[0]);
+
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints(vec![Constraint::Percentage(20), Constraint::Percentage(80)])
+        .split(chunks[1]);
+
+    // in progress downloads
+    let items: Vec<ListItem> = downloads
+        .in_progress
+        .iter()
+        .map(|(_worker_id, download)| {
+            ListItem::new(Spans::from(vec![
+                Span::raw(symbols::DOT),
+                Span::styled(
+                    format!(" download {:>2}", download.id),
+                    Style::default()
+                        .fg(Color::LightGreen)
+                        .add_modifier(Modifier::BOLD),
+                ),
+                Span::raw(format!(
+                    " ({}ms)",
+                    download.started_at.elapsed().as_millis()
+                )),
+            ]))
+        })
+        .collect();
+    let list = List::new(items);
+    f.render_widget(list, chunks[0]);
+
+    for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
+        let gauge = Gauge::default()
+            .gauge_style(Style::default().fg(Color::Yellow))
+            .ratio(download.progress / 100.0);
+        if chunks[1].top().saturating_add(i as u16) > size.bottom() {
+            continue;
+        }
+        f.render_widget(
+            gauge,
+            Rect {
+                x: chunks[1].left(),
+                y: chunks[1].top().saturating_add(i as u16),
+                width: chunks[1].width,
+                height: 1,
+            },
+        );
+    }
+}
--- a/examples/panic.rs
+++ b/examples/panic.rs
@@ -1,142 +0,0 @@
-//! 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());
-}
--- a/examples/paragraph.rs
+++ b/examples/paragraph.rs
@@ -153,28 +153,19 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
        .style(Style::default().bg(Color::White).fg(Color::Black))
        .block(create_block("Left, wrap"))
        .alignment(Alignment::Left)
-        .wrap(Wrap {
-            trim: true,
-            break_words: false,
-        });
+        .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,
-            break_words: false,
-        })
+        .wrap(Wrap { trim: true })
        .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)"))
+        .block(create_block("Right, wrap"))
        .alignment(Alignment::Right)
-        .wrap(Wrap {
-            trim: true,
-            break_words: true,
-        });
+        .wrap(Wrap { trim: true });
    f.render_widget(paragraph, chunks[3]);
 }
--- a/examples/popup.rs
+++ b/examples/popup.rs
@@ -83,10 +83,7 @@ fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
        Style::default().add_modifier(Modifier::SLOW_BLINK),
    ))
    .alignment(Alignment::Center)
-    .wrap(Wrap {
-        trim: true,
-        break_words: false,
-    });
+    .wrap(Wrap { trim: true });
    f.render_widget(paragraph, chunks[0]);

    let block = Block::default()
--- a/src/backend/crossterm.rs
+++ b/src/backend/crossterm.rs
@@ -1,5 +1,5 @@
 use crate::{
-    backend::Backend,
+    backend::{Backend, ClearType},
    buffer::Cell,
    layout::Rect,
    style::{Color, Modifier},
@@ -11,7 +11,7 @@ use crossterm::{
        Attribute as CAttribute, Color as CColor, Print, SetAttribute, SetBackgroundColor,
        SetForegroundColor,
    },
-    terminal::{self, Clear, ClearType},
+    terminal::{self, Clear},
 };
 use std::io::{self, Write};

@@ -56,7 +56,7 @@ where
        for (x, y, cell) in content {
            // Move the cursor if the previous location was not (x - 1, y)
            if !matches!(last_pos, Some(p) if x == p.0 + 1 && y == p.1) {
-                map_error(queue!(self.buffer, MoveTo(x, y)))?;
+                queue!(self.buffer, MoveTo(x, y))?;
            }
            last_pos = Some((x, y));
            if cell.modifier != modifier {
@@ -69,45 +69,60 @@ where
            }
            if cell.fg != fg {
                let color = CColor::from(cell.fg);
-                map_error(queue!(self.buffer, SetForegroundColor(color)))?;
+                queue!(self.buffer, SetForegroundColor(color))?;
                fg = cell.fg;
            }
            if cell.bg != bg {
                let color = CColor::from(cell.bg);
-                map_error(queue!(self.buffer, SetBackgroundColor(color)))?;
+                queue!(self.buffer, SetBackgroundColor(color))?;
                bg = cell.bg;
            }

-            map_error(queue!(self.buffer, Print(&cell.symbol)))?;
+            queue!(self.buffer, Print(&cell.symbol))?;
        }

-        map_error(queue!(
+        queue!(
            self.buffer,
            SetForegroundColor(CColor::Reset),
            SetBackgroundColor(CColor::Reset),
            SetAttribute(CAttribute::Reset)
-        ))
+        )
    }

    fn hide_cursor(&mut self) -> io::Result<()> {
-        map_error(execute!(self.buffer, Hide))
+        execute!(self.buffer, Hide)
    }

    fn show_cursor(&mut self) -> io::Result<()> {
-        map_error(execute!(self.buffer, Show))
+        execute!(self.buffer, Show)
    }

    fn get_cursor(&mut self) -> io::Result<(u16, u16)> {
        crossterm::cursor::position()
-            .map_err(|e| io::Error::new(io::ErrorKind::Other, e.to_string()))
    }

    fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
-        map_error(execute!(self.buffer, MoveTo(x, y)))
+        execute!(self.buffer, MoveTo(x, y))
    }

-    fn clear(&mut self) -> io::Result<()> {
-        map_error(execute!(self.buffer, Clear(ClearType::All)))
+    fn clear(&mut self, clear_type: ClearType) -> io::Result<()> {
+        execute!(
+            self.buffer,
+            Clear(match clear_type {
+                ClearType::All => crossterm::terminal::ClearType::All,
+                ClearType::AfterCursor => crossterm::terminal::ClearType::FromCursorDown,
+                ClearType::BeforeCursor => crossterm::terminal::ClearType::FromCursorUp,
+                ClearType::CurrentLine => crossterm::terminal::ClearType::CurrentLine,
+                ClearType::UntilNewLine => crossterm::terminal::ClearType::UntilNewLine,
+            })
+        )
+    }
+
+    fn append_lines(&mut self, n: u16) -> io::Result<()> {
+        for _ in 0..n {
+            queue!(self.buffer, Print("\n"))?;
+        }
+        self.buffer.flush()
    }

    fn size(&self) -> io::Result<Rect> {
@@ -122,10 +137,6 @@ where
    }
 }

-fn map_error(error: crossterm::Result<()>) -> io::Result<()> {
-    error.map_err(|e| io::Error::new(io::ErrorKind::Other, e.to_string()))
-}
-
 impl From<Color> for CColor {
    fn from(color: Color) -> Self {
        match color {
@@ -166,54 +177,54 @@ impl ModifierDiff {
        //use crossterm::Attribute;
        let removed = self.from - self.to;
        if removed.contains(Modifier::REVERSED) {
-            map_error(queue!(w, SetAttribute(CAttribute::NoReverse)))?;
+            queue!(w, SetAttribute(CAttribute::NoReverse))?;
        }
        if removed.contains(Modifier::BOLD) {
-            map_error(queue!(w, SetAttribute(CAttribute::NormalIntensity)))?;
+            queue!(w, SetAttribute(CAttribute::NormalIntensity))?;
            if self.to.contains(Modifier::DIM) {
-                map_error(queue!(w, SetAttribute(CAttribute::Dim)))?;
+                queue!(w, SetAttribute(CAttribute::Dim))?;
            }
        }
        if removed.contains(Modifier::ITALIC) {
-            map_error(queue!(w, SetAttribute(CAttribute::NoItalic)))?;
+            queue!(w, SetAttribute(CAttribute::NoItalic))?;
        }
        if removed.contains(Modifier::UNDERLINED) {
-            map_error(queue!(w, SetAttribute(CAttribute::NoUnderline)))?;
+            queue!(w, SetAttribute(CAttribute::NoUnderline))?;
        }
        if removed.contains(Modifier::DIM) {
-            map_error(queue!(w, SetAttribute(CAttribute::NormalIntensity)))?;
+            queue!(w, SetAttribute(CAttribute::NormalIntensity))?;
        }
        if removed.contains(Modifier::CROSSED_OUT) {
-            map_error(queue!(w, SetAttribute(CAttribute::NotCrossedOut)))?;
+            queue!(w, SetAttribute(CAttribute::NotCrossedOut))?;
        }
        if removed.contains(Modifier::SLOW_BLINK) || removed.contains(Modifier::RAPID_BLINK) {
-            map_error(queue!(w, SetAttribute(CAttribute::NoBlink)))?;
+            queue!(w, SetAttribute(CAttribute::NoBlink))?;
        }

        let added = self.to - self.from;
        if added.contains(Modifier::REVERSED) {
-            map_error(queue!(w, SetAttribute(CAttribute::Reverse)))?;
+            queue!(w, SetAttribute(CAttribute::Reverse))?;
        }
        if added.contains(Modifier::BOLD) {
-            map_error(queue!(w, SetAttribute(CAttribute::Bold)))?;
+            queue!(w, SetAttribute(CAttribute::Bold))?;
        }
        if added.contains(Modifier::ITALIC) {
-            map_error(queue!(w, SetAttribute(CAttribute::Italic)))?;
+            queue!(w, SetAttribute(CAttribute::Italic))?;
        }
        if added.contains(Modifier::UNDERLINED) {
-            map_error(queue!(w, SetAttribute(CAttribute::Underlined)))?;
+            queue!(w, SetAttribute(CAttribute::Underlined))?;
        }
        if added.contains(Modifier::DIM) {
-            map_error(queue!(w, SetAttribute(CAttribute::Dim)))?;
+            queue!(w, SetAttribute(CAttribute::Dim))?;
        }
        if added.contains(Modifier::CROSSED_OUT) {
-            map_error(queue!(w, SetAttribute(CAttribute::CrossedOut)))?;
+            queue!(w, SetAttribute(CAttribute::CrossedOut))?;
        }
        if added.contains(Modifier::SLOW_BLINK) {
-            map_error(queue!(w, SetAttribute(CAttribute::SlowBlink)))?;
+            queue!(w, SetAttribute(CAttribute::SlowBlink))?;
        }
        if added.contains(Modifier::RAPID_BLINK) {
-            map_error(queue!(w, SetAttribute(CAttribute::RapidBlink)))?;
+            queue!(w, SetAttribute(CAttribute::RapidBlink))?;
        }

        Ok(())
--- a/src/backend/mod.rs
+++ b/src/backend/mod.rs
@@ -16,15 +16,25 @@ pub use self::crossterm::CrosstermBackend;
 mod test;
 pub use self::test::TestBackend;

+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum ClearType {
+    All,
+    AfterCursor,
+    BeforeCursor,
+    CurrentLine,
+    UntilNewLine,
+}
+
 pub trait Backend {
    fn draw<'a, I>(&mut self, content: I) -> Result<(), io::Error>
    where
        I: Iterator<Item = (u16, u16, &'a Cell)>;
+    fn append_lines(&mut self, n: u16) -> io::Result<()>;
    fn hide_cursor(&mut self) -> Result<(), io::Error>;
    fn show_cursor(&mut self) -> Result<(), io::Error>;
    fn get_cursor(&mut self) -> Result<(u16, u16), io::Error>;
    fn set_cursor(&mut self, x: u16, y: u16) -> Result<(), io::Error>;
-    fn clear(&mut self) -> Result<(), io::Error>;
+    fn clear(&mut self, clear_type: ClearType) -> Result<(), io::Error>;
    fn size(&self) -> Result<Rect, io::Error>;
    fn flush(&mut self) -> Result<(), io::Error>;
 }
--- a/src/backend/termion.rs
+++ b/src/backend/termion.rs
@@ -1,5 +1,5 @@
-use super::Backend;
 use crate::{
+    backend::{Backend, ClearType},
    buffer::Cell,
    layout::Rect,
    style::{Color, Modifier},
@@ -42,10 +42,21 @@ impl<W> Backend for TermionBackend<W>
 where
    W: Write,
 {
-    /// Clears the entire screen and move the cursor to the top left of the screen
-    fn clear(&mut self) -> io::Result<()> {
-        write!(self.stdout, "{}", termion::clear::All)?;
-        write!(self.stdout, "{}", termion::cursor::Goto(1, 1))?;
+    fn clear(&mut self, clear_type: ClearType) -> io::Result<()> {
+        match clear_type {
+            ClearType::All => write!(self.stdout, "{}", termion::clear::All)?,
+            ClearType::AfterCursor => write!(self.stdout, "{}", termion::clear::AfterCursor)?,
+            ClearType::BeforeCursor => write!(self.stdout, "{}", termion::clear::BeforeCursor)?,
+            ClearType::CurrentLine => write!(self.stdout, "{}", termion::clear::CurrentLine)?,
+            ClearType::UntilNewLine => write!(self.stdout, "{}", termion::clear::UntilNewline)?,
+        };
+        self.stdout.flush()
+    }
+
+    fn append_lines(&mut self, n: u16) -> io::Result<()> {
+        for _ in 0..n {
+            writeln!(self.stdout)?;
+        }
        self.stdout.flush()
    }

--- a/src/backend/test.rs
+++ b/src/backend/test.rs
@@ -1,5 +1,5 @@
 use crate::{
-    backend::Backend,
+    backend::{Backend, ClearType},
    buffer::{Buffer, Cell},
    layout::Rect,
 };
@@ -117,6 +117,10 @@ impl Backend for TestBackend {
        Ok(())
    }

+    fn append_lines(&mut self, _n: u16) -> Result<(), io::Error> {
+        Ok(())
+    }
+
    fn hide_cursor(&mut self) -> Result<(), io::Error> {
        self.cursor = false;
        Ok(())
@@ -136,7 +140,7 @@ impl Backend for TestBackend {
        Ok(())
    }

-    fn clear(&mut self) -> Result<(), io::Error> {
+    fn clear(&mut self, _clear_type: ClearType) -> Result<(), io::Error> {
        self.buffer.reset();
        Ok(())
    }
--- a/src/buffer.rs
+++ b/src/buffer.rs
@@ -431,7 +431,6 @@ impl Buffer {
    pub fn diff<'a>(&self, other: &'a Buffer) -> Vec<(u16, u16, &'a Cell)> {
        let previous_buffer = &self.content;
        let next_buffer = &other.content;
-        let width = self.area.width;

        let mut updates: Vec<(u16, u16, &Cell)> = vec![];
        // Cells invalidated by drawing/replacing preceeding multi-width characters:
@@ -441,8 +440,7 @@ impl Buffer {
        let mut to_skip: usize = 0;
        for (i, (current, previous)) in next_buffer.iter().zip(previous_buffer.iter()).enumerate() {
            if (current != previous || invalidated > 0) && to_skip == 0 {
-                let x = i as u16 % width;
-                let y = i as u16 / width;
+                let (x, y) = self.pos_of(i);
                updates.push((x, y, &next_buffer[i]));
            }

--- a/src/lib.rs
+++ b/src/lib.rs
@@ -9,8 +9,8 @@
 //!
 //! ```toml
 //! [dependencies]
-//! tui = "0.18"
-//! crossterm = "0.23"
+//! tui = "0.16"
+//! crossterm = "0.22"
 //! ```
 //!
 //! The crate is using the `crossterm` backend by default that works on most platforms. But if for
@@ -20,8 +20,7 @@
 //! ```toml
 //! [dependencies]
 //! termion = "1.5"
-//! tui = { version = "0.18", default-features = false, features = ['termion'] }
-//!
+//! tui = { version = "0.16", default-features = false, features = ['termion'] }
 //! ```
 //!
 //! The same logic applies for all other available backends.
@@ -170,4 +169,4 @@ pub mod terminal;
 pub mod text;
 pub mod widgets;

-pub use self::terminal::{Frame, Terminal, TerminalOptions, Viewport};
+pub use self::terminal::{Frame, Terminal, TerminalOptions, ViewportVariant};
--- a/src/terminal.rs
+++ b/src/terminal.rs
@@ -1,40 +1,30 @@
 use crate::{
-    backend::Backend,
+    backend::{Backend, ClearType},
    buffer::Buffer,
    layout::Rect,
    widgets::{StatefulWidget, Widget},
 };
 use std::io;
+use tracing::{event, span, Level};

 #[derive(Debug, Clone, PartialEq)]
-/// UNSTABLE
-enum ResizeBehavior {
-    Fixed,
-    Auto,
-}
-
-#[derive(Debug, Clone, PartialEq)]
-/// UNSTABLE
-pub struct Viewport {
-    area: Rect,
-    resize_behavior: ResizeBehavior,
-}
-
-impl Viewport {
-    /// UNSTABLE
-    pub fn fixed(area: Rect) -> Viewport {
-        Viewport {
-            area,
-            resize_behavior: ResizeBehavior::Fixed,
-        }
-    }
+pub enum ViewportVariant {
+    Fullscreen,
+    Inline(u16),
+    Fixed(Rect),
 }

 #[derive(Debug, Clone, PartialEq)]
 /// Options to pass to [`Terminal::with_options`]
 pub struct TerminalOptions {
    /// Viewport used to draw to the terminal
-    pub viewport: Viewport,
+    pub viewport: ViewportVariant,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct Viewport {
+    variant: ViewportVariant,
+    area: Rect,
 }

 /// Interface to the terminal backed by Termion
@@ -53,6 +43,11 @@ where
    hidden_cursor: bool,
    /// Viewport
    viewport: Viewport,
+    /// Last known size of the terminal. Used to detect if the internal buffers have to be resized.
+    last_known_size: Rect,
+    /// Last known position of the cursor. Used to find the new area when the viewport is inlined
+    /// and the terminal resized.
+    last_known_cursor_pos: (u16, u16),
 }

 /// Represents a consistent terminal interface for rendering.
@@ -73,7 +68,7 @@ impl<'a, B> Frame<'a, B>
 where
    B: Backend,
 {
-    /// Terminal size, guaranteed not to change when rendering.
+    /// Frame size, guaranteed not to change when rendering.
    pub fn size(&self) -> Rect {
        self.terminal.viewport.area
    }
@@ -173,29 +168,50 @@ where
    /// Wrapper around Terminal initialization. Each buffer is initialized with a blank string and
    /// default colors for the foreground and the background
    pub fn new(backend: B) -> io::Result<Terminal<B>> {
-        let size = backend.size()?;
        Terminal::with_options(
            backend,
            TerminalOptions {
-                viewport: Viewport {
-                    area: size,
-                    resize_behavior: ResizeBehavior::Auto,
-                },
+                viewport: ViewportVariant::Fullscreen,
            },
        )
    }

-    /// UNSTABLE
-    pub fn with_options(backend: B, options: TerminalOptions) -> io::Result<Terminal<B>> {
+    pub fn with_options(mut backend: B, options: TerminalOptions) -> io::Result<Terminal<B>> {
+        let size = backend.size()?;
+        let (viewport_area, cursor_pos) = match options.viewport {
+            ViewportVariant::Fullscreen => (size, (0, 0)),
+            ViewportVariant::Inline(height) => {
+                let pos = backend.get_cursor()?;
+                let mut row = pos.1;
+                let max_height = size.height.min(height);
+                backend.append_lines(max_height.saturating_sub(1))?;
+                let missing_lines = row.saturating_add(max_height).saturating_sub(size.height);
+                if missing_lines > 0 {
+                    row = row.saturating_sub(missing_lines);
+                }
+                (
+                    Rect {
+                        x: 0,
+                        y: row,
+                        width: size.width,
+                        height: max_height,
+                    },
+                    pos,
+                )
+            }
+            ViewportVariant::Fixed(area) => (area, (area.left(), area.top())),
+        };
        Ok(Terminal {
            backend,
-            buffers: [
-                Buffer::empty(options.viewport.area),
-                Buffer::empty(options.viewport.area),
-            ],
+            buffers: [Buffer::empty(viewport_area), Buffer::empty(viewport_area)],
            current: 0,
            hidden_cursor: false,
-            viewport: options.viewport,
+            viewport: Viewport {
+                variant: options.viewport,
+                area: viewport_area,
+            },
+            last_known_size: size,
+            last_known_cursor_pos: cursor_pos,
        })
    }

@@ -225,28 +241,61 @@ where
        let previous_buffer = &self.buffers[1 - self.current];
        let current_buffer = &self.buffers[self.current];
        let updates = previous_buffer.diff(current_buffer);
+        if let Some((col, row, _)) = updates.last() {
+            self.last_known_cursor_pos = (*col, *row);
+        }
        self.backend.draw(updates.into_iter())
    }

-    /// Updates the Terminal so that internal buffers match the requested size. Requested size will
-    /// be saved so the size can remain consistent when rendering.
-    /// This leads to a full clear of the screen.
-    pub fn resize(&mut self, area: Rect) -> io::Result<()> {
-        self.buffers[self.current].resize(area);
-        self.buffers[1 - self.current].resize(area);
-        self.viewport.area = area;
-        self.clear()
+    /// Queries the backend for size and resizes if it doesn't match the previous size.
+    pub fn resize(&mut self) -> io::Result<()> {
+        let size = self.size()?;
+        if self.last_known_size == size {
+            return Ok(());
+        }
+
+        event!(Level::DEBUG, last_known_size = ?self.last_known_size, ?size, "terminal size changed");
+
+        let next_area = match self.viewport.variant {
+            ViewportVariant::Fullscreen => size,
+            ViewportVariant::Inline(height) => {
+                let (_, mut row) = self.get_cursor()?;
+                let offset_in_previous_viewport = self
+                    .last_known_cursor_pos
+                    .1
+                    .saturating_sub(self.viewport.area.top());
+                let max_height = height.min(size.height);
+                let lines_after_cursor = height
+                    .saturating_sub(offset_in_previous_viewport)
+                    .saturating_sub(1);
+                let available_lines = size.height.saturating_sub(row).saturating_sub(1);
+                let missing_lines = lines_after_cursor.saturating_sub(available_lines);
+                self.backend.append_lines(lines_after_cursor)?;
+                if missing_lines > 0 {
+                    row = row.saturating_sub(missing_lines);
+                }
+                row = row.saturating_sub(offset_in_previous_viewport);
+                Rect {
+                    x: 0,
+                    y: row,
+                    width: size.width,
+                    height: max_height,
+                }
+            }
+            ViewportVariant::Fixed(area) => area,
+        };
+        self.set_viewport_area(next_area);
+        self.clear()?;
+
+        self.last_known_size = size;
+        Ok(())
    }

-    /// Queries the backend for size and resizes if it doesn't match the previous size.
-    pub fn autoresize(&mut self) -> io::Result<()> {
-        if self.viewport.resize_behavior == ResizeBehavior::Auto {
-            let size = self.size()?;
-            if size != self.viewport.area {
-                self.resize(size)?;
-            }
-        };
-        Ok(())
+    fn set_viewport_area(&mut self, area: Rect) {
+        self.viewport.area = area;
+        self.buffers[self.current].resize(area);
+        self.buffers[1 - self.current].resize(area);
+        event!(Level::DEBUG, area = ?area, "viewport changed");
    }

    /// Synchronizes terminal size, calls the rendering closure, flushes the current internal state
@@ -255,9 +304,12 @@ where
    where
        F: FnOnce(&mut Frame<B>),
    {
+        let span = span!(Level::DEBUG, "draw");
+        let _guard = span.enter();
+
        // Autoresize - otherwise we get glitches if shrinking or potential desync between widgets
        // and the terminal (if growing), which may OOB.
-        self.autoresize()?;
+        self.resize()?;

        let mut frame = self.get_frame();
        f(&mut frame);
@@ -283,9 +335,12 @@ where

        // Flush
        self.backend.flush()?;
+
+        event!(Level::DEBUG, "completed frame");
+
        Ok(CompletedFrame {
            buffer: &self.buffers[1 - self.current],
-            area: self.viewport.area,
+            area: self.last_known_size,
        })
    }

@@ -306,12 +361,28 @@ where
    }

    pub fn set_cursor(&mut self, x: u16, y: u16) -> io::Result<()> {
-        self.backend.set_cursor(x, y)
+        self.backend.set_cursor(x, y)?;
+        self.last_known_cursor_pos = (x, y);
+        Ok(())
    }

    /// Clear the terminal and force a full redraw on the next draw call.
    pub fn clear(&mut self) -> io::Result<()> {
-        self.backend.clear()?;
+        event!(Level::DEBUG, "clear");
+        match self.viewport.variant {
+            ViewportVariant::Fullscreen => self.backend.clear(ClearType::All)?,
+            ViewportVariant::Inline(_) => {
+                self.backend
+                    .set_cursor(self.viewport.area.left(), self.viewport.area.top())?;
+                self.backend.clear(ClearType::AfterCursor)?;
+            }
+            ViewportVariant::Fixed(area) => {
+                for row in area.top()..area.bottom() {
+                    self.backend.set_cursor(0, row)?;
+                    self.backend.clear(ClearType::AfterCursor)?;
+                }
+            }
+        }
        // Reset the back buffer to make sure the next update will redraw everything.
        self.buffers[1 - self.current].reset();
        Ok(())
@@ -321,4 +392,97 @@ where
    pub fn size(&self) -> io::Result<Rect> {
        self.backend.size()
    }
+
+    /// Insert some content before the current inline viewport. This has no effect when the
+    /// viewport is fullscreen.
+    ///
+    /// This function scrolls down the current viewport by the given height. The newly freed space is
+    /// then made available to the `draw_fn` closure through a writable `Buffer`.
+    ///
+    /// Before:
+    /// ```ignore
+    /// +-------------------+
+    /// |                   |
+    /// |      viewport     |
+    /// |                   |
+    /// +-------------------+
+    /// ```
+    ///
+    /// After:
+    /// ```ignore
+    /// +-------------------+
+    /// |      buffer       |
+    /// +-------------------+
+    /// +-------------------+
+    /// |                   |
+    /// |      viewport     |
+    /// |                   |
+    /// +-------------------+
+    /// ```
+    ///
+    /// # Examples
+    ///
+    /// ## Insert a single line before the current viewport
+    ///
+    /// ```rust
+    /// # use tui::widgets::{Paragraph, Widget};
+    /// # use tui::text::{Spans, Span};
+    /// # use tui::style::{Color, Style};
+    /// # use tui::{Terminal};
+    /// # use tui::backend::TestBackend;
+    /// # let backend = TestBackend::new(10, 10);
+    /// # let mut terminal = Terminal::new(backend).unwrap();
+    /// terminal.insert_before(1, |buf| {
+    ///     Paragraph::new(Spans::from(vec![
+    ///         Span::raw("This line will be added "),
+    ///         Span::styled("before", Style::default().fg(Color::Blue)),
+    ///         Span::raw(" the current viewport")
+    ///     ])).render(buf.area, buf);
+    /// });
+    /// ```
+    pub fn insert_before<F>(&mut self, height: u16, draw_fn: F) -> io::Result<()>
+    where
+        F: FnOnce(&mut Buffer),
+    {
+        let span = span!(Level::DEBUG, "insert_before");
+        let _guard = span.enter();
+        if !matches!(self.viewport.variant, ViewportVariant::Inline(_)) {
+            return Ok(());
+        }
+
+        self.clear()?;
+        let height = height.min(self.last_known_size.height);
+        self.backend.append_lines(height)?;
+        let missing_lines =
+            height.saturating_sub(self.last_known_size.bottom() - self.viewport.area.top());
+        let area = Rect {
+            x: self.viewport.area.left(),
+            y: self.viewport.area.top().saturating_sub(missing_lines),
+            width: self.viewport.area.width,
+            height,
+        };
+        let mut buffer = Buffer::empty(area);
+
+        draw_fn(&mut buffer);
+
+        let iter = buffer.content.iter().enumerate().map(|(i, c)| {
+            let (x, y) = buffer.pos_of(i);
+            (x, y, c)
+        });
+        self.backend.draw(iter)?;
+        self.backend.flush()?;
+
+        let remaining_lines = self.last_known_size.height - area.bottom();
+        let missing_lines = self.viewport.area.height.saturating_sub(remaining_lines);
+        self.backend.append_lines(self.viewport.area.height)?;
+
+        self.set_viewport_area(Rect {
+            x: area.left(),
+            y: area.bottom().saturating_sub(missing_lines),
+            width: area.width,
+            height: self.viewport.area.height,
+        });
+
+        Ok(())
+    }
 }
--- a/src/widgets/paragraph.rs
+++ b/src/widgets/paragraph.rs
@@ -40,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, break_words: false });
+///     .wrap(Wrap { trim: true });
 /// ```
 #[derive(Debug, Clone)]
 pub struct Paragraph<'a> {
@@ -70,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, break_words: false });
+/// Paragraph::new(bullet_points.clone()).wrap(Wrap { trim: true });
 /// // Some indented points:
 /// // - First thing goes here and is
 /// // long so that it wraps
@@ -78,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, break_words: false });
+/// Paragraph::new(bullet_points).wrap(Wrap { trim: false });
 /// // Some indented points:
 /// //     - First thing goes here
 /// // and is long so that it wraps
@@ -89,8 +89,6 @@ 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> {
@@ -164,21 +162,15 @@ impl<'a> Widget for Paragraph<'a> {
                }))
        });

-        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 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 y = 0;
        while let Some((current_line, current_line_width)) = line_composer.next_line() {
            if y >= self.scroll.0 {
--- a/src/widgets/reflow.rs
+++ b/src/widgets/reflow.rs
@@ -19,7 +19,6 @@ 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> {
@@ -27,7 +26,6 @@ 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,
@@ -35,7 +33,6 @@ impl<'a, 'b> WordWrapper<'a, 'b> {
            current_line: vec![],
            next_line: vec![],
            trim,
-            break_words,
        }
    }
 }
@@ -90,12 +87,11 @@ 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 && !self.break_words {
-                        (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 {
+                    (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:
                {
@@ -239,7 +235,7 @@ mod test {
    use unicode_segmentation::UnicodeSegmentation;

    enum Composer {
-        WordWrapper { trim: bool, break_words: bool },
+        WordWrapper { trim: bool },
        LineTruncator,
    }

@@ -248,12 +244,9 @@ 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, break_words } => Box::new(WordWrapper::new(
-                &mut styled,
-                text_area_width,
-                trim,
-                break_words,
-            )),
+            Composer::WordWrapper { trim } => {
+                Box::new(WordWrapper::new(&mut styled, text_area_width, trim))
+            }
            Composer::LineTruncator => Box::new(LineTruncator::new(&mut styled, text_area_width)),
        };
        let mut lines = vec![];
@@ -275,14 +268,8 @@ mod test {
        let width = 40;
        for i in 1..width {
            let text = "a".repeat(i);
-            let (word_wrapper, _) = run_composer(
-                Composer::WordWrapper {
-                    trim: true,
-                    break_words: true,
-                },
-                &text,
-                width as u16,
-            );
+            let (word_wrapper, _) =
+                run_composer(Composer::WordWrapper { trim: 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);
@@ -295,14 +282,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);

        let wrapped: Vec<&str> = text.split('\n').collect();
@@ -314,14 +294,8 @@ mod test {
    fn line_composer_long_word() {
        let width = 20;
        let text = "abcdefghijklmnopabcdefghijklmnopabcdefghijklmnopabcdefghijklmno";
-        let (word_wrapper, _) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
-            text,
-            width as u16,
-        );
+        let (word_wrapper, _) =
+            run_composer(Composer::WordWrapper { trim: true }, text, width as u16);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width as u16);

        let wrapped = vec![
@@ -346,19 +320,10 @@ 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,
-                break_words: true,
-            },
-            text,
-            width as u16,
-        );
+        let (word_wrapper_single_space, _) =
+            run_composer(Composer::WordWrapper { trim: true }, text, width as u16);
        let (word_wrapper_multi_space, _) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
+            Composer::WordWrapper { trim: true },
            text_multi_space,
            width as u16,
        );
@@ -381,14 +346,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);

        let expected: Vec<&str> = Vec::new();
@@ -400,14 +358,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);

        let expected: Vec<&str> = UnicodeSegmentation::graphemes(text, true)
@@ -422,14 +373,7 @@ mod test {
        let width = 1;
        let text = "コンピュータ上で文字を扱う場合、典型的には文字\naaaによる通信を行う場合にその\
                    両端点では、";
-        let (word_wrapper, _) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: 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"]);
@@ -440,14 +384,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
        assert_eq!(
            word_wrapper,
            vec![
@@ -465,14 +402,8 @@ mod test {
        let width = 20;
        let text = "コンピュータ上で文字を扱う場合、典型的には文字による通信を行う場合にその両端点\
                    では、";
-        let (word_wrapper, word_wrapper_width) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, word_wrapper_width) =
+            run_composer(Composer::WordWrapper { trim: true }, text, width);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
        assert_eq!(line_truncator, vec!["コンピュータ上で文字"]);
        let wrapped = vec![
@@ -490,14 +421,7 @@ mod test {
    fn line_composer_leading_whitespace_removal() {
        let width = 20;
        let text = "AAAAAAAAAAAAAAAAAAAA    AAA";
-        let (word_wrapper, _) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: 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"]);
@@ -508,14 +432,7 @@ mod test {
    fn line_composer_lots_of_spaces() {
        let width = 20;
        let text = "                                                                     ";
-        let (word_wrapper, _) = run_composer(
-            Composer::WordWrapper {
-                trim: true,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: true }, text, width);
        let (line_truncator, _) = run_composer(Composer::LineTruncator, text, width);
        assert_eq!(word_wrapper, vec![""]);
        assert_eq!(line_truncator, vec!["                    "]);
@@ -527,14 +444,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: 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
@@ -553,14 +463,8 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, word_wrapper_width) =
+            run_composer(Composer::WordWrapper { trim: true }, text, width);
        assert_eq!(
            word_wrapper,
            vec![
@@ -581,26 +485,13 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: 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,
-                break_words: true,
-            },
-            &text_space,
-            width,
-        );
+        let text_space = text.replace("\u{00a0}", " ");
+        let (word_wrapper_space, _) =
+            run_composer(Composer::WordWrapper { trim: true }, &text_space, width);
        assert_eq!(word_wrapper_space, vec!["AAAAAAAAAAAAAAA AAAA", "AAA",]);
    }

@@ -608,14 +499,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
        assert_eq!(word_wrapper, vec!["AAAAAAAAAAAAAAAAAAAA", "   AAA",]);
    }

@@ -623,14 +507,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
        assert_eq!(
            word_wrapper,
            vec!["AAA AAA", "AAAAA AA", "AAAAAA", " B", "  C", "   D"]
@@ -641,14 +518,7 @@ 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,
-                break_words: true,
-            },
-            text,
-            width,
-        );
+        let (word_wrapper, _) = run_composer(Composer::WordWrapper { trim: false }, text, width);
        assert_eq!(
            word_wrapper,
            vec![
--- a/tests/backend_termion.rs
+++ b/tests/backend_termion.rs
@@ -8,14 +8,14 @@ fn backend_termion_should_only_write_diffs() -> Result<(), Box<dyn std::error::E
    {
        use tui::{
            backend::TermionBackend, layout::Rect, widgets::Paragraph, Terminal, TerminalOptions,
-            Viewport,
+            ViewportVariant,
        };
        let backend = TermionBackend::new(&mut stdout);
        let area = Rect::new(0, 0, 3, 1);
        let mut terminal = Terminal::with_options(
            backend,
            TerminalOptions {
-                viewport: Viewport::fixed(area),
+                viewport: ViewportVariant::Fixed(area),
            },
        )?;
        terminal.draw(|f| {
--- a/tests/widgets_paragraph.rs
+++ b/tests/widgets_paragraph.rs
@@ -25,10 +25,7 @@ fn widgets_paragraph_can_wrap_its_content() {
                let paragraph = Paragraph::new(text)
                    .block(Block::default().borders(Borders::ALL))
                    .alignment(alignment)
-                    .wrap(Wrap {
-                        trim: true,
-                        break_words: false,
-                    });
+                    .wrap(Wrap { trim: true });
                f.render_widget(paragraph, size);
            })
            .unwrap();
@@ -82,76 +79,6 @@ 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);
@@ -164,10 +91,7 @@ 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,
-                    break_words: false,
-                });
+                .wrap(Wrap { trim: true });
            f.render_widget(paragraph, size);
        })
        .unwrap();
@@ -199,10 +123,7 @@ 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,
-                    break_words: false,
-                });
+                .wrap(Wrap { trim: true });
            f.render_widget(paragraph, size);
        })
        .unwrap();