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::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 },
57 common: Common::default(),
58 }
59 }
60
61 /// Sets the text shown, dimmed, while the area is empty.
62 pub fn placeholder(mut self, text: impl IntoProp<String>) -> TextArea {
63 self.input.placeholder = Some(text.into_prop());
64 self
65 }
66
67 /// Takes the keyboard focus whenever this turns true.
68 pub fn focus(mut self, focus: impl IntoProp<bool>) -> TextArea {
69 self.input.focus = Some(focus.into_prop());
70 self
71 }
72
73 /// When on, the default, lines wrap at words to the area's width, 200
74 /// unless its style sets one. Off, each line is as long as it is and
75 /// the area as wide as its longest, so a sideways `ScrollView` scrolls
76 /// it.
77 pub fn wrap(mut self, wrap: impl IntoProp<bool>) -> TextArea {
78 self.input.wrap = Some(wrap.into_prop());
79 self
80 }
81
82 /// Runs `handler` with the text when Ctrl+Enter is pressed in the area.
83 pub fn on_accept(mut self, handler: impl Fn(&Cx, &str) + 'static) -> TextArea {
84 self.input.on_accept = Some(Rc::new(Handler::new(handler)));
85 self
86 }
87
88 /// Sets the style. An area cuts its text to the inside of its border.
89 /// Its text takes the font, color, alignment, line height and
90 /// decorations it inherits or sets, as a [`Text`](crate::Text) does.
91 pub fn style(mut self, style: impl IntoProp<Style>) -> TextArea {
92 self.common.style = Some(style.into_prop());
93 self
94 }
95
96 visibility_methods!();
97}
98
99impl Widget for TextArea {
100 fn into_element(self: Box<Self>) -> Element {
101 Element {
102 name: "TextArea",
103 common: self.common,
104 kind: ElementKind::Input(Box::new(self.input)),
105 children: Vec::new(),
106 }
107 }
108}