1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

use euclid::Size2D;

use crate::{event::Event, unit::Cell, Printer};

/// A UI element
pub trait View<T, M> {
    /// Draws this element
    fn draw(&self, printer: &Printer, focused: bool);

    /// Calculate the view's content-based size with minimum width
    ///
    /// This is not necessarily the view's *absolute* minimum width; in most
    /// cases that would end up being zero, which isn't useful. Instead, the
    /// value computed is a *sensible* minimum that, if [`draw`](View::draw)
    /// were called with this function's return value as the
    /// [`Printer`](crate::Printer)'s size, would produce a visually-acceptable
    /// result.
    ///
    /// # Examples
    ///
    /// The [`text`](crate::view::text) view finds the visual length of the
    /// [visually-longest](unicode_segmentation::UnicodeSegmentation::graphemes)
    /// sequence of [non-whitespace](std::str.split_whitespace) characters (or
    /// in other words, longest word including punctuation) and reports that
    /// length as its width. The height value is computed by
    /// [`textwrap`](textwrap)ing with that width and reporting the amount of
    /// lines it would take to display the text.
    fn width(&self) -> Size2D<u16, Cell>;

    /// Calculate the view's content-based size with minimum height
    ///
    /// This is not necessarily the view's *absolute* minimum height; in most
    /// cases that would end up being zero, which isn't useful. Instead, the
    /// value computed is a *sensible* minimum that, if [`draw`](View::draw)
    /// were called with this function's return value as the
    /// [`Printer`](crate::Printer)'s size, would produce a visually-acceptable
    /// result.
    ///
    /// # Examples
    ///
    /// The [`text`](crate::view::text) view reports its height as the number of
    /// lines in its content and its width as the visual length of the visually
    /// longest line.
    fn height(&self) -> Size2D<u16, Cell>;

    /// Given a constraint, calculate the size of this view
    fn layout(&self, constraint: Size2D<u16, Cell>) -> Size2D<u16, Cell>;

    /// Process an event and optionally produce messages
    fn event(
        &mut self,
        event: &Event<T>,
        focused: bool,
    ) -> Box<dyn Iterator<Item = M>>;

    /// Whether this element can be interacted with by the user
    ///
    /// Returning `false` from this method does not opt the implementor out of
    /// receiving events, only from acquiring focus. In other words, the
    /// `focused` argument to [`event()`] will be `false` after returning
    /// `false` from this function. Also, returning `true` doesn't imply that
    /// `focused` will be `true`, only that it may eventually be `true` when the
    /// user focuses this element.
    ///
    /// [`event()`]: View::event
    fn interactive(&self) -> bool;
}