Struct Image 

pub struct Image<'a> { /* private fields */ }

Fixed size image widget that uses Protocol.

The widget does not react to area resizes. Its advantage lies in that the Protocol needs only one initial resize.

The image won’t render if it doesn’t fit, unless Image::allow_clipping has been set.

// let picker = Picker::from_query_studio()?;
let image = image::ImageReader::open("./assets/NixOS.png")?.decode()?;
let proto = picker.new_protocol(image, Size::new(20, 10), Resize::Fit(None))?;

terminal.draw(|f| {
    f.render_widget(Image::new(&proto), f.area());
});

Implementations

impl<'a> Image<'a>

pub fn new(image: &'a Protocol) -> Self

Examples found in repository

examples/demo/main.rs (line 363)

fn ui(f: &mut Frame<'_>, app: &mut App) {
    let outer_block = Block::default()
        .borders(Borders::TOP)
        .title(app.title.as_str());

    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([
            Constraint::Percentage(app.split_percent),
            Constraint::Percentage(100 - app.split_percent),
        ])
        .split(outer_block.inner(f.area()));
    f.render_widget(outer_block, f.area());

    let left_chunks = vertical_layout().split(chunks[0]);
    let right_chunks = vertical_layout().split(chunks[1]);

    let chunks_left_top = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
        .split(left_chunks[0]);

    let block_left_top = block("Fixed");
    let area = block_left_top.inner(chunks_left_top[0]);
    f.render_widget(
        paragraph(app.background.as_str()).style(Color::Yellow),
        area,
    );
    f.render_widget(block_left_top, chunks_left_top[0]);
    if app.show_images != ShowImages::Resized {
        // Let it be surrounded by styled text.
        let area = Rect {
            x: area.x + 1,
            y: area.y + 1,
            width: area.width.saturating_sub(2),
            height: area.height.saturating_sub(2),
        };

        if let Some(placeholder_area) = app.image_static.needs_placeholder(area) {
            let placeholder = Block::bordered()
                .border_type(BorderType::QuadrantOutside)
                .bg(Color::DarkGray);
            f.render_widget(Clear {}, placeholder.inner(placeholder_area));
            f.render_widget(placeholder, placeholder_area);
        } else {
            let image = Image::new(&app.image_static).allow_clipping(true);
            f.render_widget(image, area);
        }
    }

    let block_middle_top = block("Sliced");
    let area = block_middle_top.inner(chunks_left_top[1]);
    app.image_sliced_viewport = Some(area.into());
    f.render_widget(
        paragraph(app.background.as_str()).style(Color::LightBlue),
        area,
    );
    f.render_widget(block_middle_top, chunks_left_top[1]);
    if app.show_images != ShowImages::Resized {
        let (pos, _, _) = app.image_sliced_position;
        let image = SlicedImage::new(&app.image_sliced, pos);
        f.render_widget(image, area);
    }

    let chunks_left_bottom = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
        .split(left_chunks[1]);

    app.render_resized_image(f, Resize::Crop(None), chunks_left_bottom[0]);
    app.render_resized_image(f, Resize::Scale(None), chunks_left_bottom[1]);
    app.render_resized_image(f, Resize::Fit(None), right_chunks[0]);

    let block_right_bottom = block("Help");
    let area = block_right_bottom.inner(right_chunks[1]);
    f.render_widget(
        paragraph(vec![
            Line::from(format!(
                "Font size: {}×{}",
                app.picker.font_size().width,
                app.picker.font_size().height
            )),
            Line::from(format!("Protocol: {:?}", app.picker.protocol_type())),
            Line::from("Key bindings:"),
            Line::from(vec![
                Span::from("H").green(),
                Span::from("/"),
                Span::from("L").green(),
                Span::from(": resize panes"),
            ]),
            Line::from(vec![Span::from("o").green(), Span::from(": cycle image")]),
            Line::from(vec![
                Span::from("t").green(),
                Span::from(format!(": toggle ({:?})", app.show_images)),
            ]),
            Line::from(vec![
                Span::from("h").green(),
                Span::from("/"),
                Span::from("j").green(),
                Span::from("/"),
                Span::from("k").green(),
                Span::from("/"),
                Span::from("l").green(),
                Span::from(": move"),
            ]),
            Line::from(vec![
                Span::from("a").green(),
                Span::from(": toggle animation"),
            ]),
        ]),
        area,
    );
    f.render_widget(block_right_bottom, right_chunks[1]);
}

pub fn allow_clipping(self, allow: bool) -> Self

Allow clipping the image if the render area is smaller than the image, and if the protocol supports it (protocol::kitty and protocol::halfblocks).

This is disabled by default to make the behavior consistent.

See also protocol::Protocol::needs_placeholder, which is an excellent complement if you need to render something when the image couldn’t.

terminal.draw(|f| {
    if let Some(placeholder_area) = proto.needs_placeholder(f.area()) {
        // Render `Box` or something with placeholder_area.
    } else {
        f.render_widget(Image::new(&proto).allow_clipping(true), f.area());
    }
});

Examples found in repository

examples/demo/main.rs (line 363)

fn ui(f: &mut Frame<'_>, app: &mut App) {
    let outer_block = Block::default()
        .borders(Borders::TOP)
        .title(app.title.as_str());

    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([
            Constraint::Percentage(app.split_percent),
            Constraint::Percentage(100 - app.split_percent),
        ])
        .split(outer_block.inner(f.area()));
    f.render_widget(outer_block, f.area());

    let left_chunks = vertical_layout().split(chunks[0]);
    let right_chunks = vertical_layout().split(chunks[1]);

    let chunks_left_top = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
        .split(left_chunks[0]);

    let block_left_top = block("Fixed");
    let area = block_left_top.inner(chunks_left_top[0]);
    f.render_widget(
        paragraph(app.background.as_str()).style(Color::Yellow),
        area,
    );
    f.render_widget(block_left_top, chunks_left_top[0]);
    if app.show_images != ShowImages::Resized {
        // Let it be surrounded by styled text.
        let area = Rect {
            x: area.x + 1,
            y: area.y + 1,
            width: area.width.saturating_sub(2),
            height: area.height.saturating_sub(2),
        };

        if let Some(placeholder_area) = app.image_static.needs_placeholder(area) {
            let placeholder = Block::bordered()
                .border_type(BorderType::QuadrantOutside)
                .bg(Color::DarkGray);
            f.render_widget(Clear {}, placeholder.inner(placeholder_area));
            f.render_widget(placeholder, placeholder_area);
        } else {
            let image = Image::new(&app.image_static).allow_clipping(true);
            f.render_widget(image, area);
        }
    }

    let block_middle_top = block("Sliced");
    let area = block_middle_top.inner(chunks_left_top[1]);
    app.image_sliced_viewport = Some(area.into());
    f.render_widget(
        paragraph(app.background.as_str()).style(Color::LightBlue),
        area,
    );
    f.render_widget(block_middle_top, chunks_left_top[1]);
    if app.show_images != ShowImages::Resized {
        let (pos, _, _) = app.image_sliced_position;
        let image = SlicedImage::new(&app.image_sliced, pos);
        f.render_widget(image, area);
    }

    let chunks_left_bottom = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
        .split(left_chunks[1]);

    app.render_resized_image(f, Resize::Crop(None), chunks_left_bottom[0]);
    app.render_resized_image(f, Resize::Scale(None), chunks_left_bottom[1]);
    app.render_resized_image(f, Resize::Fit(None), right_chunks[0]);

    let block_right_bottom = block("Help");
    let area = block_right_bottom.inner(right_chunks[1]);
    f.render_widget(
        paragraph(vec![
            Line::from(format!(
                "Font size: {}×{}",
                app.picker.font_size().width,
                app.picker.font_size().height
            )),
            Line::from(format!("Protocol: {:?}", app.picker.protocol_type())),
            Line::from("Key bindings:"),
            Line::from(vec![
                Span::from("H").green(),
                Span::from("/"),
                Span::from("L").green(),
                Span::from(": resize panes"),
            ]),
            Line::from(vec![Span::from("o").green(), Span::from(": cycle image")]),
            Line::from(vec![
                Span::from("t").green(),
                Span::from(format!(": toggle ({:?})", app.show_images)),
            ]),
            Line::from(vec![
                Span::from("h").green(),
                Span::from("/"),
                Span::from("j").green(),
                Span::from("/"),
                Span::from("k").green(),
                Span::from("/"),
                Span::from("l").green(),
                Span::from(": move"),
            ]),
            Line::from(vec![
                Span::from("a").green(),
                Span::from(": toggle animation"),
            ]),
        ]),
        area,
    );
    f.render_widget(block_right_bottom, right_chunks[1]);
}

Trait Implementations

impl Widget for Image<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.