itsscb/ratatui
1
0
Fork 0
mirror of https://github.com/ratatui/ratatui.git synced 2025-09-28 21:41:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update crate, lib and readme links (#771)

Browse Source 
Link to the contributing, changelog, and breaking changes docs at the
top of the page instead of just in in the main part of the doc. This
makes it easier to find them.

Rearrange the links to be in a more logical order.

Use link refs for all the links

Fix up the CI link to point to the right workflow
This commit is contained in:
Josh McKinney 2024-01-08 23:52:47 -08:00 committed by GitHub
parent 8dd177a051
commit 388aa467f1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 59 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@ -25,29 +25,22 @@
<div align="center"> <div align="center">
[![Crate Badge]](https://crates.io/crates/ratatui) [![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![License
[![License Badge]](./LICENSE) Badge]](./LICENSE)<br>
[![CI Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+) [![Codecov Badge]][Codecov] [![Deps.rs Badge]][Deps.rs] [![Discord Badge]][Discord Server]
[![Docs Badge]](https://docs.rs/crate/ratatui/)<br> [![Matrix Badge]][Matrix]<br>
[![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui)
[![Codecov Badge]](https://app.codecov.io/gh/ratatui-org/ratatui)
[![Discord Badge]](https://discord.gg/pMCEU9hNEj)
[![Matrix Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
[Documentation](https://docs.rs/ratatui) [Ratatui Website] · [API Docs] · [Examples]<br>
· [Ratatui Website](https://ratatui.rs) [Contributing] · [Changelog] · [Breaking Changes]<br>
· [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples) [Report a bug] · [Request a Feature] · [Create a Pull Request]
· [Report a bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
· [Request a Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
· [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)
</div> </div>
# Ratatui # Ratatui
[Ratatui] is a crate for cooking up terminal user interfaces in Rust. It is a lightweight [Ratatui][Ratatui Website] is a crate for cooking up terminal user interfaces in Rust. It is a
library that provides a set of widgets and utilities to build complex Rust TUIs. Ratatui was lightweight library that provides a set of widgets and utilities to build complex Rust TUIs.
forked from the [tui-rs] crate in 2023 in order to continue its development. Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its development.
## Installation ## Installation
@ -66,16 +59,16 @@ section of the [Ratatui Website] for more details on how to use other backends (
Ratatui is based on the principle of immediate rendering with intermediate buffers. This means Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
that for each frame, your app must render all widgets that are supposed to be part of the UI. that for each frame, your app must render all widgets that are supposed to be part of the UI.
This is in contrast to the retained mode style of rendering where widgets are updated and then This is in contrast to the retained mode style of rendering where widgets are updated and then
automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website] for automatically redrawn on the next frame. See the [Rendering] section of the [Ratatui Website]
more info. for more info.
## Other documentation ## Other documentation
- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
- [API Docs] - the full API documentation for the library on docs.rs.
- [Examples] - a collection of examples that demonstrate how to use the library. - [Examples] - a collection of examples that demonstrate how to use the library.
- [API Documentation] - the full API documentation for the library on docs.rs.
- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
- [Contributing] - Please read this if you are interested in contributing to the project. - [Contributing] - Please read this if you are interested in contributing to the project.
- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
- [Breaking Changes] - a list of breaking changes in the library. - [Breaking Changes] - a list of breaking changes in the library.
## Quickstart ## Quickstart
@ -83,8 +76,8 @@ more info.
The following example demonstrates the minimal amount of code necessary to setup a terminal and The following example demonstrates the minimal amount of code necessary to setup a terminal and
render "Hello World!". The full code for this example which contains a little more detail is in render "Hello World!". The full code for this example which contains a little more detail is in
[hello_world.rs]. For more guidance on different ways to structure your application see the [hello_world.rs]. For more guidance on different ways to structure your application see the
[Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the various [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
[Examples]. There are also several starter templates available: various [Examples]. There are also several starter templates available:
- [template] - [template]
- [async-template] (book and template) - [async-template] (book and template)
@ -117,8 +110,8 @@ module] and the [Backends] section of the [Ratatui Website] for more info.
The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
[`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`] [`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website] for using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website]
more info. for more info.
### Handling events ### Handling events
@ -131,10 +124,11 @@ Website] for more info. For example, if you are using [Crossterm], you can use t
```rust ```rust
use std::io::{self, stdout}; use std::io::{self, stdout};
use crossterm::{ use crossterm::{
event::{self, Event, KeyCode}, event::{self, Event, KeyCode},
terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
ExecutableCommand, ExecutableCommand,
terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}
}; };
use ratatui::{prelude::*, widgets::*}; use ratatui::{prelude::*, widgets::*};
@ -160,7 +154,7 @@ fn handle_events() -> io::Result<bool> {
if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') { if key.kind == event::KeyEventKind::Press && key.code == KeyCode::Char('q') {
return Ok(true); return Ok(true);
} }
} }
} }
Ok(false) Ok(false)
} }
@ -195,7 +189,7 @@ fn ui(frame: &mut Frame) {
Constraint::Length(1), Constraint::Length(1),
Constraint::Min(0), Constraint::Min(0),
Constraint::Length(1), Constraint::Length(1),
] ],
) )
.split(frame.size()); .split(frame.size());
frame.render_widget( frame.render_widget(
@ -209,7 +203,7 @@ fn ui(frame: &mut Frame) {
let inner_layout = Layout::new( let inner_layout = Layout::new(
Direction::Horizontal, Direction::Horizontal,
[Constraint::Percentage(50), Constraint::Percentage(50)] [Constraint::Percentage(50), Constraint::Percentage(50)],
) )
.split(main_layout[1]); .split(main_layout[1]);
frame.render_widget( frame.render_widget(
@ -251,7 +245,7 @@ fn ui(frame: &mut Frame) {
Constraint::Length(1), Constraint::Length(1),
Constraint::Length(1), Constraint::Length(1),
Constraint::Min(0), Constraint::Min(0),
] ],
) )
.split(frame.size()); .split(frame.size());
@ -302,9 +296,12 @@ Running this example produces the following output:
[template]: https://github.com/ratatui-org/template [template]: https://github.com/ratatui-org/template
[async-template]: https://ratatui-org.github.io/async-template [async-template]: https://ratatui-org.github.io/async-template
[Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
[Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
[Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
[Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
[git-cliff]: https://git-cliff.org [git-cliff]: https://git-cliff.org
[Conventional Commits]: https://www.conventionalcommits.org [Conventional Commits]: https://www.conventionalcommits.org
[API Documentation]: https://docs.rs/ratatui [API Docs]: https://docs.rs/ratatui
[Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
[Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md [Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
[Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md [Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
@ -324,24 +321,29 @@ Running this example produces the following output:
[`Backend`]: backend::Backend [`Backend`]: backend::Backend
[`backend` module]: backend [`backend` module]: backend
[`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html [`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
[Ratatui]: https://ratatui.rs [Crate]: https://crates.io/crates/ratatui
[Crossterm]: https://crates.io/crates/crossterm [Crossterm]: https://crates.io/crates/crossterm
[Termion]: https://crates.io/crates/termion [Termion]: https://crates.io/crates/termion
[Termwiz]: https://crates.io/crates/termwiz [Termwiz]: https://crates.io/crates/termwiz
[tui-rs]: https://crates.io/crates/tui [tui-rs]: https://crates.io/crates/tui
[hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
[CI Badge]: [CI Badge]:
https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
[CI Workflow]: https://github.com/ratatui-org/ratatui/actions/workflows/ci.yml
[Codecov Badge]: [Codecov Badge]:
https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
[Dependencies Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square [Codecov]: https://app.codecov.io/gh/ratatui-org/ratatui
[Deps.rs Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
[Deps.rs]: https://deps.rs/repo/github/ratatui-org/ratatui
[Discord Badge]: [Discord Badge]:
https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
[Discord Server]: https://discord.gg/pMCEU9hNEj
[Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square [Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
[Matrix Badge]: [Matrix Badge]:
https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
[Matrix]: https://matrix.to/#/#ratatui:matrix.org
<!-- cargo-rdme end --> <!-- cargo-rdme end -->

46
src/lib.rs
View File

@ -4,29 +4,21 @@
//! //!
//! <div align="center"> //! <div align="center">
//! //!
//! [![Crate Badge]](https://crates.io/crates/ratatui) //! [![Crate Badge]][Crate] [![Docs Badge]][API Docs] [![CI Badge]][CI Workflow] [![License
//! [![License Badge]](./LICENSE) //! Badge]](./LICENSE)<br>
//! [![CI Badge]](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+) //! [![Codecov Badge]][Codecov] [![Deps.rs Badge]][Deps.rs] [![Discord Badge]][Discord Server]
//! [![Docs Badge]](https://docs.rs/crate/ratatui/)<br> //! [![Matrix Badge]][Matrix]<br>
//! [![Dependencies Badge]](https://deps.rs/repo/github/ratatui-org/ratatui)
//! [![Codecov Badge]](https://app.codecov.io/gh/ratatui-org/ratatui)
//! [![Discord Badge]](https://discord.gg/pMCEU9hNEj)
//! [![Matrix Badge]](https://matrix.to/#/#ratatui:matrix.org)<br>
//! //!
//! [Documentation](https://docs.rs/ratatui) //! [Ratatui Website] · [API Docs] · [Examples] · [Changelog] · [Breaking Changes]<br>
//! · [Ratatui Website](https://ratatui.rs) //! [Contributing] · [Report a bug] · [Request a Feature] · [Create a Pull Request]
//! · [Examples](https://github.com/ratatui-org/ratatui/tree/main/examples)
//! · [Report a bug](https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md)
//! · [Request a Feature](https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md)
//! · [Send a Pull Request](https://github.com/ratatui-org/ratatui/compare)
//! //!
//! </div> //! </div>
//! //!
//! # Ratatui //! # Ratatui
//! //!
//! [Ratatui] is a crate for cooking up terminal user interfaces in Rust. It is a lightweight //! [Ratatui][Ratatui Website] is a crate for cooking up terminal user interfaces in Rust. It is a
//! library that provides a set of widgets and utilities to build complex Rust TUIs. Ratatui was //! lightweight library that provides a set of widgets and utilities to build complex Rust TUIs.
//! forked from the [tui-rs] crate in 2023 in order to continue its development. //! Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its development.
//! //!
//! ## Installation //! ## Installation
//! //!
@ -51,10 +43,10 @@
//! ## Other documentation //! ## Other documentation
//! //!
//! - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials //! - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
//! - [API Docs] - the full API documentation for the library on docs.rs.
//! - [Examples] - a collection of examples that demonstrate how to use the library. //! - [Examples] - a collection of examples that demonstrate how to use the library.
//! - [API Documentation] - the full API documentation for the library on docs.rs.
//! - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
//! - [Contributing] - Please read this if you are interested in contributing to the project. //! - [Contributing] - Please read this if you are interested in contributing to the project.
//! - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
//! - [Breaking Changes] - a list of breaking changes in the library. //! - [Breaking Changes] - a list of breaking changes in the library.
//! //!
//! ## Quickstart //! ## Quickstart
@ -300,9 +292,12 @@
//! [template]: https://github.com/ratatui-org/template //! [template]: https://github.com/ratatui-org/template
//! [async-template]: https://ratatui-org.github.io/async-template //! [async-template]: https://ratatui-org.github.io/async-template
//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples //! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
//! [Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
//! [Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
//! [Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
//! [git-cliff]: https://git-cliff.org //! [git-cliff]: https://git-cliff.org
//! [Conventional Commits]: https://www.conventionalcommits.org //! [Conventional Commits]: https://www.conventionalcommits.org
//! [API Documentation]: https://docs.rs/ratatui //! [API Docs]: https://docs.rs/ratatui
//! [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md //! [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
//! [Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md //! [Contributing]: https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
//! [Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md //! [Breaking Changes]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
@ -322,24 +317,29 @@
//! [`Backend`]: backend::Backend //! [`Backend`]: backend::Backend
//! [`backend` module]: backend //! [`backend` module]: backend
//! [`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html //! [`crossterm::event`]: https://docs.rs/crossterm/latest/crossterm/event/index.html
//! [Ratatui]: https://ratatui.rs //! [Crate]: https://crates.io/crates/ratatui
//! [Crossterm]: https://crates.io/crates/crossterm //! [Crossterm]: https://crates.io/crates/crossterm
//! [Termion]: https://crates.io/crates/termion //! [Termion]: https://crates.io/crates/termion
//! [Termwiz]: https://crates.io/crates/termwiz //! [Termwiz]: https://crates.io/crates/termwiz
//! [tui-rs]: https://crates.io/crates/tui //! [tui-rs]: https://crates.io/crates/tui
//! [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs //! [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
//! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square //! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
//! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
//! [CI Badge]: //! [CI Badge]:
//! https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github //! https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
//! [CI Workflow]: https://github.com/ratatui-org/ratatui/actions/workflows/ci.yml
//! [Codecov Badge]: //! [Codecov Badge]:
//! https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST //! https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST
//! [Dependencies Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square //! [Codecov]: https://app.codecov.io/gh/ratatui-org/ratatui
//! [Deps.rs Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
//! [Deps.rs]: https://deps.rs/repo/github/ratatui-org/ratatui
//! [Discord Badge]: //! [Discord Badge]:
//! https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square //! https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square
//! [Discord Server]: https://discord.gg/pMCEU9hNEj
//! [Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square //! [Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square
//! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
//! [Matrix Badge]: //! [Matrix Badge]:
//! https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix //! https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix
//! [Matrix]: https://matrix.to/#/#ratatui:matrix.org
// show the feature flags in the generated documentation // show the feature flags in the generated documentation
#![cfg_attr(docsrs, feature(doc_auto_cfg))] #![cfg_attr(docsrs, feature(doc_auto_cfg))]