Skip to main content

crabshell_ui/
text_area.rs

1//! [`TextArea`], a multi-line text editor. It is a text field with line
2//! breaks: the tree, the keys, the pointer, the clipboard and input
3//! methods are the field's.
4
5use std::rc::Rc;
6
7use crabshell_reactive::Signal;
8
9use crate::cx::Cx;
10use crate::input::Handler;
11use crate::prop::IntoProp;
12use crate::style::{Color, Style};
13use crate::text_input::InputProps;
14use crate::widgets::{Common, Element, ElementKind, Widget, visibility_methods};
15
16/// A multi-line text editor. It edits the text in a shared signal as a
17/// [`TextInput`](crate::TextInput) does, and takes the focus the same
18/// ways. Enter breaks the line, and Ctrl+Enter runs
19/// [`on_accept`](Self::on_accept). Up and Down move by line, keeping the
20/// caret's place across, Home and End go to the ends of the line as it
21/// is wrapped, Ctrl+Home and Ctrl+End to the ends of the text, and
22/// PageUp and PageDown by the height of the [`ScrollView`](crate::ScrollView)
23/// around it, or 10 lines. Tab types a tab, drawn four spaces wide, and
24/// Shift+Tab and Ctrl+Tab move the focus back and on.
25///
26/// The area is as tall as its lines, at least one. Put it in a
27/// `ScrollView` to cap its height; when the caret leaves the view, the
28/// view scrolls the least that shows it.
29///
30/// ```
31/// use crabshell_ui::{Cx, ScrollView, Style, TextArea};
32///
33/// fn note(cx: &Cx) -> ScrollView {
34///     let text = cx.signal(String::new());
35///     ScrollView::new(TextArea::new(text).placeholder("Write a note"))
36///         .style(Style::new().height(120.0))
37/// }
38/// ```
39pub struct TextArea {
40  input: InputProps,
41  common: Common,
42}
43
44impl TextArea {
45  /// An area editing `text`.
46  pub fn new(text: Signal<String>) -> TextArea {
47    TextArea {
48      input: InputProps {
49        text,
50        placeholder: None,
51        password: None,
52        focus: None,
53        on_accept: None,
54        multiline: true,
55        wrap: None,
56        max_length: None,
57        read_only: None,
58        selection_color: None,
59        selected_text_color: None,
60      },
61      common: Common::default(),
62    }
63  }
64
65  /// Sets the text shown, dimmed, while the area is empty.
66  pub fn placeholder(mut self, text: impl IntoProp<String>) -> TextArea {
67    self.input.placeholder = Some(text.into_prop());
68    self
69  }
70
71  /// Lets the area hold at most `max` characters, a line break counting
72  /// as one, or any number with `None`, the default. Typing, pasting and
73  /// an input method stop there, cutting what they bring between
74  /// graphemes. Text set from outside, or already there when the limit
75  /// drops, is cut to it, and the cut text is written back to the signal.
76  pub fn max_length(mut self, max: impl IntoProp<Option<usize>>) -> TextArea {
77    self.input.max_length = Some(max.into_prop());
78    self
79  }
80
81  /// While on, off by default, the area takes no edits: typing, Enter
82  /// and Tab, deleting, cutting, pasting and input methods leave it
83  /// alone, and their keys go on to the window's `on_key`. The caret,
84  /// selection and Ctrl+C still work, Ctrl+Enter still runs `on_accept`,
85  /// and text set from outside still shows.
86  pub fn read_only(mut self, on: impl IntoProp<bool>) -> TextArea {
87    self.input.read_only = Some(on.into_prop());
88    self
89  }
90
91  /// Sets the color the selection is drawn in behind the text. By
92  /// default, or with `None`, it is the text's color at a third of its
93  /// alpha.
94  pub fn selection_color(mut self, color: impl IntoProp<Option<Color>>) -> TextArea {
95    self.input.selection_color = Some(color.into_prop());
96    self
97  }
98
99  /// Sets the color the selected text is drawn in, over any span or
100  /// link color. By default, or with `None`, it keeps its own color.
101  /// Underlines and strikethroughs keep theirs.
102  pub fn selected_text_color(mut self, color: impl IntoProp<Option<Color>>) -> TextArea {
103    self.input.selected_text_color = Some(color.into_prop());
104    self
105  }
106
107  /// Takes the keyboard focus whenever this turns true.
108  pub fn focus(mut self, focus: impl IntoProp<bool>) -> TextArea {
109    self.input.focus = Some(focus.into_prop());
110    self
111  }
112
113  /// When on, the default, lines wrap at words to the area's width, 200
114  /// unless its style sets one. Off, each line is as long as it is and
115  /// the area as wide as its longest, so a sideways `ScrollView` scrolls
116  /// it.
117  pub fn wrap(mut self, wrap: impl IntoProp<bool>) -> TextArea {
118    self.input.wrap = Some(wrap.into_prop());
119    self
120  }
121
122  /// Runs `handler` with the text when Ctrl+Enter is pressed in the area.
123  pub fn on_accept(mut self, handler: impl Fn(&Cx, &str) + 'static) -> TextArea {
124    self.input.on_accept = Some(Rc::new(Handler::new(handler)));
125    self
126  }
127
128  /// Sets the style. An area cuts its text to the inside of its border.
129  /// Its text takes the font, color, alignment, line height and
130  /// decorations it inherits or sets, as a [`Text`](crate::Text) does.
131  pub fn style(mut self, style: impl IntoProp<Style>) -> TextArea {
132    self.common.style = Some(style.into_prop());
133    self
134  }
135
136  visibility_methods!();
137}
138
139impl Widget for TextArea {
140  fn into_element(self: Box<Self>) -> Element {
141    Element {
142      name: "TextArea",
143      common: self.common,
144      kind: ElementKind::Input(Box::new(self.input)),
145      children: Vec::new(),
146    }
147  }
148}