Struct cursive_async_view::AsyncView

pub struct AsyncView<T: View> { /* fields omitted */ }

An AsyncView is a wrapper view that displays a loading screen, until the child view is ready to be created. The view can be used in two different ways.

Poll-based AsyncView

The poll-based AsyncView is constructed via the AsyncView::new function and regularly calls the provided poll_ready function. It indicates whether the child view is available or not by returning an AsyncState enum. The poll_ready callback should only check for data to be available and create the child view when the data got available. It must never block until the data is available or do heavy calculations!

Use a different thread for long taking calculations. Check the bg_task example for an example on how to use a dedicated calculation thread with the AsyncView.

Example usage of the poll-based variant

use std::time::{Instant, Duration};
use cursive::{views::TextView, Cursive, CursiveExt};
use cursive_async_view::{AsyncView, AsyncState};

let mut siv = Cursive::default();
let instant = Instant::now();
let async_view = AsyncView::new(&mut siv, move || {
    // check if the view can be created
    if instant.elapsed() > Duration::from_secs(10) {
        AsyncState::Available(
            TextView::new("Yay!\n\nThe content has loaded!")
        )
    } else {
        AsyncState::Pending
    }
});

siv.add_layer(async_view);
// siv.run();

The content will be displayed after 10 seconds.

Producing view data in a background thread

The second variant produces custom data in a background thread via the provided bg_task function. The produced data is then sent to the cursive thread and given to the provided view_creator function. This function should construct the child view and return it to the async view.

All heavy work must be done in the bg_task function. Otherwise, the cursive event loop will be blocked, preventing any rendering or event handling taking place.

Example usage for the background thread variant

use std::thread;
use std::time::Duration;

use cursive::views::TextView;
use cursive::{Cursive, CursiveExt};
use cursive_async_view::AsyncView;

let mut siv = Cursive::default();
let async_view = AsyncView::new_with_bg_creator(&mut siv, move || {
    // this function is executed in a background thread, so we can block
    // here as long as we like
    thread::sleep(Duration::from_secs(10));

    // enough blocking, let's show the content
    Ok("Yeet! It worked 🖖")
}, TextView::new); // create a text view from the string

siv.add_layer(async_view);
// siv.run();

The content will be displayed after 10 seconds.

Implementations

impl<T: View> AsyncView<T>

pub fn new<F>(siv: &mut Cursive, ready_poll: F) -> Self where
    F: FnMut() -> AsyncState<T> + 'static, 

Create a new AsyncView instance. The cursive reference is used to control the refresh rate of the terminal when the loading animation is running. In order to show the view, it has to be directly or indirectly added to a cursive layer like any other view.

The ready_poll function will be called regularly until the view has either been loaded or errored. Use this function only to check whether your data is available. Do not run heavy calculations in this function. Instead use a dedicated thread for it as shown in the bg_task example.

pub fn new_with_bg_creator<F, C, D>(
    siv: &mut Cursive,
    bg_task: F,
    view_creator: C
) -> Self where
    D: Send + 'static,
    F: FnOnce() -> Result<D, String> + Send + 'static,
    C: FnMut(D) -> T + 'static, 

Create a new AsyncView instance. The cursive reference is used to control the refresh rate of the terminal when the loading animation is running. In order to show the view, it has to be directly or indirectly added to a cursive layer like any other view.

The bg_task function is executed on a background thread called cursive-async-view::bg_task. It should be used to produce data of type D which is converted to a view by the view_creator function.

pub fn with_width(self, width: usize) -> Self

Mark the maximum allowed width in characters, the loading animation may consume. By default, the width will be inherited by the parent view.

pub fn with_height(self, height: usize) -> Self

Mark the maximum allowed height in characters, the loading animation may consume. By default, the height will be inherited by the parent view.

pub fn with_animation_fn<F>(self, animation_fn: F) -> Self where
    F: Fn(usize, usize, usize) -> AnimationFrame + 'static, 

Set a custom animation function for this view, indicating that the wrapped view is not available yet. See the default_animation function reference for an example on how to create a custom animation function.

pub fn with_error_fn<F>(self, error_fn: F) -> Self where
    F: Fn(&str, usize, usize, usize, usize) -> AnimationFrame + 'static, 

Set a custom error animation function for this view, indicating that the wrapped view has failed to load. See the default_error function reference for an example on how to create a custom error animation function.

pub fn set_width(&mut self, width: usize)

Set the maximum allowed width in characters, the loading animation may consume.

pub fn set_height(&mut self, height: usize)

Set the maximum allowed height in characters, the loading animation may consume.

pub fn set_animation_fn<F>(&mut self, animation_fn: F) where
    F: Fn(usize, usize, usize) -> AnimationFrame + 'static, 

Set a custom animation function for this view, indicating that the wrapped view is not available yet. See the default_animation function reference for an example on how to create a custom animation function.

This function may be set at any time. The loading animation can be changed even if the previous loading animation has already started.

pub fn set_error_fn<F>(&mut self, error_fn: F) where
    F: Fn(&str, usize, usize, usize, usize) -> AnimationFrame + 'static, 

Set a custom error animation function for this view, indicating that the wrapped view has failed to load. See the default_error function reference for an example on how to create a custom error animation function.

This function may be set at any time. The error animation can be changed even if the previous error animation has already started.

pub fn inherit_width(&mut self)

Make the loading animation inherit its width from the parent view. This is the default.

pub fn inherit_height(&mut self)

Make the loading animation inherit its height from the parent view. This is the default.

Trait Implementations

impl<T: View> Drop for AsyncView<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: View + Sized> View for AsyncView<T>

fn draw(&self, printer: &Printer<'_, '_>)

Draws the view with the given printer (includes bounds) and focus.

fn layout(&mut self, vec: Vec2)

Called once the size for this view has been decided.

fn needs_relayout(&self) -> bool

Should return true if the view content changed since the last call to layout().

fn required_size(&mut self, constraint: Vec2) -> Vec2

Returns the minimum size the view requires with the given restrictions.

fn on_event(&mut self, ev: Event) -> EventResult

Called when an event is received (key press, mouse event, …).

fn call_on_any<'a>(&mut self, sel: &Selector<'_>, cb: AnyCb<'a>)

Runs a closure on the view identified by the given selector.

fn focus_view(&mut self, sel: &Selector<'_>) -> Result<(), ViewNotFound>

Moves the focus to the view identified by the given selector.

fn take_focus(&mut self, source: Direction) -> bool

This view is offered focus. Will it take it?

fn important_area(&self, view_size: Vec2) -> Rect

What part of the view is important and should be visible?

pub fn type_name(&self) -> &'static str

Returns the type of this view.