cursive_async_view/
lib.rs

1//! This project provides a wrapper view with a loading screen for
2//! [gyscos/cursive](https://github.com/gyscos/cursive) views. The loading screen
3//! will disappear once the wrapped view is fully loaded. This is useful for
4//! displaying views which need data that takes long to construct or depend on
5//! e.g. the network.
6//!
7//! # Asynchronous view loading without progress information
8//!
9//! If you can't tell the progress during a long taking preparation of data for
10//! a view, you may wrap the creation of this view in an `AsyncView`. This will
11//! display a loading animation until the inner view is ready to be drawn.
12//!
13//! ```
14//! use std::time::{Instant, Duration};
15//! use cursive::{views::TextView, Cursive, CursiveExt};
16//! use cursive_async_view::{AsyncView, AsyncState};
17//!
18//! let mut siv = Cursive::default();
19//! let instant = Instant::now();
20//! let async_view = AsyncView::new(&mut siv, move || {
21//!     if instant.elapsed() > Duration::from_secs(10) {
22//!         AsyncState::Available(
23//!             TextView::new("Yay!\n\nThe content has loaded!")
24//!         )
25//!     } else {
26//!         AsyncState::Pending
27//!     }
28//! });
29//!
30//! siv.add_layer(async_view);
31//! // siv.run();
32//! ```
33//!
34//! Refer to the `AsyncView` struct level documentation for a detailed
35//! explanation or to the `simple` example located in the source code
36//! repository.
37//!
38//! If you need to do a blocking operation during the construction of the child
39//! view, you may have a look at the alternate `new_with_bg_task` constructor.
40//!
41//! ```
42//! use std::thread;
43//! use std::time::Duration;
44//!
45//! use cursive::views::TextView;
46//! use cursive::{Cursive, CursiveExt};
47//! use cursive_async_view::AsyncView;
48//!
49//! let mut siv = Cursive::default();
50//! let async_view = AsyncView::new_with_bg_creator(&mut siv, move || {
51//!     // this function is executed in a background thread, so we can block
52//!     // here as long as we like
53//!     thread::sleep(Duration::from_secs(10));
54//!
55//!     // enough blocking, let's show the content
56//!     Ok("Yeet! It worked 🖖")
57//! }, TextView::new); // create a text view from the string
58//!
59//! siv.add_layer(async_view);
60//! // siv.run();
61//! ```
62//!
63//! Refer to the `AsyncView` struct level documentation for a detailed
64//! explanation or to the `bg_task` example located in the source code
65//! repository.
66//!
67//! # Asynchronous view loading with a progress bar
68//!
69//! If you have information about the progress a long taking view creation has made,
70//! you can wrap the creation in an `AsyncProgressView`. This will display a progress
71//! bar until the inner view is ready to be drawn.
72//!
73//! ```
74//! use cursive::{views::TextView, Cursive, CursiveExt};
75//! use cursive_async_view::{AsyncProgressView, AsyncProgressState};
76//!
77//! let mut siv = Cursive::default();
78//! let start = std::time::Instant::now();
79//! let async_view = AsyncProgressView::new(&mut siv, move || {
80//!     if start.elapsed().as_secs() < 3 {
81//!         AsyncProgressState::Pending(start.elapsed().as_secs() as f32 / 3f32)
82//!     } else {
83//!         AsyncProgressState::Available(TextView::new("Finally it loaded!"))
84//!     }
85//! });
86//!
87//! siv.add_layer(async_view);
88//! // siv.run();
89//! ```
90
91mod infinite;
92mod progress;
93mod utils;
94
95pub use infinite::{default_animation, default_error, AnimationFrame, AsyncState, AsyncView};
96pub use progress::{
97    default_progress, default_progress_error, AnimationProgressFrame, AsyncProgressState,
98    AsyncProgressView,
99};
100
101doc_comment::doctest!("../README.md");