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::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}