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}