zng_wgt_text/
lib.rs

1#![doc(html_favicon_url = "https://zng-ui.github.io/res/zng-logo-icon.png")]
2#![doc(html_logo_url = "https://zng-ui.github.io/res/zng-logo.png")]
3//!
4//! Text widgets and properties.
5//!
6//! # Crate
7//!
8#![doc = include_str!(concat!("../", std::env!("CARGO_PKG_README")))]
9// suppress nag about very simple boxed closure signatures.
10#![expect(clippy::type_complexity)]
11#![warn(unused_extern_crates)]
12#![warn(missing_docs)]
13
14zng_wgt::enable_widget_macros!();
15
16use zng_wgt::prelude::*;
17
18#[macro_use]
19extern crate bitflags;
20
21pub mod cmd;
22pub mod node;
23mod text_properties;
24pub use text_properties::*;
25
26#[doc(hidden)]
27pub use zng_wgt::prelude::formatx as __formatx;
28
29pub mod icon;
30
31/// A configured text run.
32///
33/// # Examples
34///
35/// ```
36/// # zng_wgt::enable_widget_macros!();
37/// # use zng_wgt_text::*;
38/// # fn main() {
39/// let hello_txt = Text! {
40///     font_family = "Arial";
41///     font_size = 18;
42///     txt = "Hello!";
43/// };
44/// # }
45/// ```
46/// # Shorthand
47///
48/// The `Text!` macro provides shorthand syntax that matches the [`formatx!`] input, but outputs a text widget:
49///
50/// ```
51/// # zng_wgt::enable_widget_macros!();
52/// # use zng_wgt_text::*;
53/// # fn main() {
54/// let txt = Text!("Hello!");
55///
56/// let name = "World";
57/// let fmt = Text!("Hello {}!", name);
58///
59/// let expr = Text!({
60///     let mut s = String::new();
61///     s.push('a');
62///     s
63/// });
64/// # }
65/// ```
66///
67/// The code abode is equivalent to:
68///
69/// ```
70/// # zng_wgt::enable_widget_macros!();
71/// # use zng_wgt_text::*;
72/// # fn main() {
73/// # use zng_wgt::prelude::*;
74/// let txt = Text! {
75///     txt = formatx!("Hello!");
76/// };
77///
78/// let name = "World";
79/// let fmt = Text! {
80///     txt = formatx!("Hello {}!", name);
81/// };
82///
83/// let expr = Text! {
84///     txt = {
85///         let mut s = String::new();
86///         s.push('a');
87///         s
88///     };
89/// };
90/// # }
91/// ```
92///
93/// [`formatx!`]: zng_wgt::prelude::formatx
94#[widget($crate::Text {
95    ($txt:literal) => {
96        txt = $crate::__formatx!($txt);
97    };
98    ($txt:expr) => {
99        txt = $txt;
100    };
101    ($txt:tt, $($format:tt)*) => {
102        txt = $crate::__formatx!($txt, $($format)*);
103    };
104})]
105#[rustfmt::skip]
106pub struct Text(
107    FontMix<
108    TextFillMix<
109    TextAlignMix<
110    TextWrapMix<
111    TextDecorationMix<
112    TextSpacingMix<
113    TextTransformMix<
114    LangMix<
115    FontFeaturesMix<
116    ParagraphMix<
117    TextEditMix<
118    SelectionToolbarMix<
119    TextInspectMix<
120    WidgetBase
121    >>>>>>>>>>>>>
122);
123
124impl Text {
125    /// Context variables used by properties in text.
126    pub fn context_vars_set(set: &mut ContextValueSet) {
127        FontMix::<()>::context_vars_set(set);
128        TextFillMix::<()>::context_vars_set(set);
129        TextAlignMix::<()>::context_vars_set(set);
130        TextWrapMix::<()>::context_vars_set(set);
131        TextDecorationMix::<()>::context_vars_set(set);
132        TextSpacingMix::<()>::context_vars_set(set);
133        TextTransformMix::<()>::context_vars_set(set);
134        FontFeaturesMix::<()>::context_vars_set(set);
135        TextEditMix::<()>::context_vars_set(set);
136        SelectionToolbarMix::<()>::context_vars_set(set);
137        TextInspectMix::<()>::context_vars_set(set);
138
139        LangMix::<()>::context_vars_set(set);
140    }
141}
142
143/// The text string.
144///
145/// Set to an empty string (`""`) by default.
146#[property(CHILD, default(""), widget_impl(Text))]
147pub fn txt(wgt: &mut WidgetBuilding, txt: impl IntoVar<Txt>) {
148    let _ = txt;
149    wgt.expect_property_capture();
150}
151
152/// Value that is parsed from the text and displayed as the text.
153///
154/// This is an alternative to [`txt`] that converts to and from `T` if it can be formatted to display text and can parse, with
155/// parse error that can display.
156///
157/// If the parse operation fails the value variable is not updated and the error display text is set in [`DATA.invalidate`], you
158/// can use [`has_data_error`] and [`get_data_error_txt`] to display the error.
159///
160/// See also [`txt_parse_live`] for manually controlling when parse happens.
161///
162/// See also [`txt_parse_on_stop`] for only parsing when the user stops typing.
163///
164/// [`txt`]: fn@txt
165/// [`txt_parse_live`]: fn@txt_parse_live
166/// [`txt_parse_on_stop`]: fn@txt_parse_on_stop
167/// [`DATA.invalidate`]: zng_wgt_data::DATA::invalidate
168/// [`has_data_error`]: fn@zng_wgt_data::has_data_error
169/// [`get_data_error_txt`]: fn@zng_wgt_data::get_data_error_txt
170#[property(CHILD, widget_impl(Text))]
171pub fn txt_parse<T>(child: impl IntoUiNode, value: impl IntoVar<T>) -> UiNode
172where
173    T: TxtParseValue,
174{
175    node::parse_text(child, value)
176}
177
178/// Represents a type that can be a var value, parse and display.
179///
180/// This trait is used by [`txt_parse`]. It is implemented for all types that are
181/// `VarValue + FromStr + Display where FromStr::Err: Display`.
182///
183/// [`txt_parse`]: fn@txt_parse
184#[diagnostic::on_unimplemented(note = "`TxtParseValue` is implemented for all `T: VarValue + Display + FromStr<Error: Display>")]
185pub trait TxtParseValue: VarValue {
186    /// Try parse `Self` from `txt`, formats the error for display.
187    ///
188    /// Note that the widget context is not available here as this method is called in the app context.
189    fn from_txt(txt: &Txt) -> Result<Self, Txt>;
190    /// Display the value, the returned text can be parsed back to an equal value.
191    ///
192    /// Note that the widget context is not available here as this method is called in the app context.
193    fn to_txt(&self) -> Txt;
194}
195impl<T> TxtParseValue for T
196where
197    T: VarValue + std::str::FromStr + std::fmt::Display,
198    <Self as std::str::FromStr>::Err: std::fmt::Display,
199{
200    fn from_txt(txt: &Txt) -> Result<Self, Txt> {
201        T::from_str(txt).map_err(|e| e.to_txt())
202    }
203
204    fn to_txt(&self) -> Txt {
205        ToTxt::to_txt(self)
206    }
207}
208
209impl Text {
210    fn widget_intrinsic(&mut self) {
211        self.widget_builder().push_build_action(|wgt| {
212            let child = node::render_text();
213            let child = node::non_interactive_caret(child);
214            let child = node::interactive_carets(child);
215            let child = node::render_overlines(child);
216            let child = node::render_strikethroughs(child);
217            let child = node::render_underlines(child);
218            let child = node::render_ime_preview_underlines(child);
219            let child = node::render_selection(child);
220            wgt.set_child(child);
221
222            wgt.push_intrinsic(NestGroup::CHILD_LAYOUT + 100, "layout_text", |child| {
223                let child = node::selection_toolbar_node(child);
224                node::layout_text(child)
225            });
226
227            let text = if wgt.property(property_id!(Self::txt_parse)).is_some() {
228                wgt.capture_var(property_id!(Self::txt)).unwrap_or_else(|| var(Txt::from_str("")))
229            } else {
230                wgt.capture_var_or_default(property_id!(Self::txt))
231            };
232            wgt.push_intrinsic(NestGroup::EVENT, "resolve_text", |child| {
233                let child = node::rich_text_component(child, "text");
234                node::resolve_text(child, text)
235            });
236        });
237    }
238}
239
240#[doc(hidden)]
241pub use zng_ext_font::{FontStyle as __FontStyle, FontWeight as __FontWeight};
242
243///<span data-del-macro-root></span> A simple text run with **bold** font weight.
244///
245/// The input syntax is the same as the shorthand [`Text!`].
246///
247/// # Configure
248///
249/// Apart from the font weight this widget can be configured with contextual properties like [`Text!`].
250///
251/// [`Text!`]: struct@Text
252#[macro_export]
253macro_rules! Strong {
254    ($txt:expr) => {
255        $crate::Text! {
256            txt = $txt;
257            font_weight = $crate::__FontWeight::BOLD;
258        }
259    };
260    ($txt:tt, $($format:tt)*) => {
261        $crate::Text! {
262            txt = $crate::__formatx!($txt, $($format)*);
263            font_weight = $crate::__FontWeight::BOLD;
264        }
265    };
266}
267
268///<span data-del-macro-root></span> A simple text run with *italic* font style.
269///
270/// The input syntax is the same as the shorthand [`Text!`].
271///
272/// # Configure
273///
274/// Apart from the font style this widget can be configured with contextual properties like [`Text!`].
275///
276/// [`Text!`]: struct@Text
277#[macro_export]
278macro_rules! Em {
279    ($txt:expr) => {
280        $crate::Text! {
281            txt = $txt;
282            font_style = $crate::__FontStyle::Italic;
283        }
284    };
285    ($txt:tt, $($format:tt)*) => {
286        $crate::Text! {
287            txt = $crate::__formatx!($txt, $($format)*);
288            font_style = $crate::__FontStyle::Italic;
289        }
290    };
291}
zng_wgt_text/lib.rs

zng_wgt_text/
lib.rs
