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/// In a text widget this property is captured, in other widgets sets the child node to a text widget.
146#[property(CHILD, default(""), widget_impl(Text))]
147pub fn txt(wgt: &mut WidgetBuilding, txt: impl IntoVar<Txt>) {
148    wgt.set_child(Text!(txt));
149}
150
151/// Value that is parsed from the text and displayed as the text.
152///
153/// This is an alternative to [`txt`] that converts to and from `T` if it can be formatted to display text and can parse, with
154/// parse error that can display.
155///
156/// If the parse operation fails the value variable is not updated and the error display text is set in [`DATA.invalidate`], you
157/// can use [`has_data_error`] and [`get_data_error_txt`] to display the error.
158///
159/// See also [`txt_parse_live`] for manually controlling when parse happens.
160///
161/// See also [`txt_parse_on_stop`] for only parsing when the user stops typing.
162///
163/// [`txt`]: fn@txt
164/// [`txt_parse_live`]: fn@txt_parse_live
165/// [`txt_parse_on_stop`]: fn@txt_parse_on_stop
166/// [`DATA.invalidate`]: zng_wgt_data::DATA::invalidate
167/// [`has_data_error`]: fn@zng_wgt_data::has_data_error
168/// [`get_data_error_txt`]: fn@zng_wgt_data::get_data_error_txt
169#[property(CHILD, widget_impl(Text))]
170pub fn txt_parse<T>(child: impl IntoUiNode, value: impl IntoVar<T>) -> UiNode
171where
172    T: TxtParseValue,
173{
174    node::parse_text(child, value)
175}
176
177/// Represents a type that can be a var value, parse and display.
178///
179/// This trait is used by [`txt_parse`]. It is implemented for all types that are
180/// `VarValue + FromStr + Display where FromStr::Err: Display`.
181///
182/// [`txt_parse`]: fn@txt_parse
183#[diagnostic::on_unimplemented(note = "`TxtParseValue` is implemented for all `T: VarValue + Display + FromStr<Error: Display>")]
184pub trait TxtParseValue: VarValue {
185    /// Try parse `Self` from `txt`, formats the error for display.
186    ///
187    /// Note that the widget context is not available here as this method is called in the app context.
188    fn from_txt(txt: &Txt) -> Result<Self, Txt>;
189    /// Display the value, the returned text can be parsed back to an equal value.
190    ///
191    /// Note that the widget context is not available here as this method is called in the app context.
192    fn to_txt(&self) -> Txt;
193}
194impl<T> TxtParseValue for T
195where
196    T: VarValue + std::str::FromStr + std::fmt::Display,
197    <Self as std::str::FromStr>::Err: std::fmt::Display,
198{
199    fn from_txt(txt: &Txt) -> Result<Self, Txt> {
200        T::from_str(txt).map_err(|e| e.to_txt())
201    }
202
203    fn to_txt(&self) -> Txt {
204        ToTxt::to_txt(self)
205    }
206}
207
208impl Text {
209    fn widget_intrinsic(&mut self) {
210        self.widget_builder().push_build_action(|wgt| {
211            let child = node::render_text();
212            let child = node::non_interactive_caret(child);
213            let child = node::interactive_carets(child);
214            let child = node::render_overlines(child);
215            let child = node::render_strikethroughs(child);
216            let child = node::render_underlines(child);
217            let child = node::render_ime_preview_underlines(child);
218            let child = node::render_selection(child);
219            wgt.set_child(child);
220
221            wgt.push_intrinsic(NestGroup::CHILD_LAYOUT + 100, "layout_text", |child| {
222                let child = node::selection_toolbar_node(child);
223                node::layout_text(child)
224            });
225
226            let text = if wgt.property(property_id!(Self::txt_parse)).is_some() {
227                wgt.capture_var(property_id!(Self::txt)).unwrap_or_else(|| var(Txt::from_str("")))
228            } else {
229                wgt.capture_var_or_default(property_id!(Self::txt))
230            };
231            wgt.push_intrinsic(NestGroup::EVENT, "resolve_text", |child| {
232                let child = node::rich_text_component(child, "text");
233                node::resolve_text(child, text)
234            });
235        });
236    }
237}
238
239#[doc(hidden)]
240pub use zng_ext_font::{FontStyle as __FontStyle, FontWeight as __FontWeight};
241
242///<span data-del-macro-root></span> A simple text run with **bold** font weight.
243///
244/// The input syntax is the same as the shorthand [`Text!`].
245///
246/// # Configure
247///
248/// Apart from the font weight this widget can be configured with contextual properties like [`Text!`].
249///
250/// [`Text!`]: struct@Text
251#[macro_export]
252macro_rules! Strong {
253    ($txt:expr) => {
254        $crate::Text! {
255            txt = $txt;
256            font_weight = $crate::__FontWeight::BOLD;
257        }
258    };
259    ($txt:tt, $($format:tt)*) => {
260        $crate::Text! {
261            txt = $crate::__formatx!($txt, $($format)*);
262            font_weight = $crate::__FontWeight::BOLD;
263        }
264    };
265}
266
267///<span data-del-macro-root></span> A simple text run with *italic* font style.
268///
269/// The input syntax is the same as the shorthand [`Text!`].
270///
271/// # Configure
272///
273/// Apart from the font style this widget can be configured with contextual properties like [`Text!`].
274///
275/// [`Text!`]: struct@Text
276#[macro_export]
277macro_rules! Em {
278    ($txt:expr) => {
279        $crate::Text! {
280            txt = $txt;
281            font_style = $crate::__FontStyle::Italic;
282        }
283    };
284    ($txt:tt, $($format:tt)*) => {
285        $crate::Text! {
286            txt = $crate::__formatx!($txt, $($format)*);
287            font_style = $crate::__FontStyle::Italic;
288        }
289    };
290}
zng_wgt_text/lib.rs

zng_wgt_text/
lib.rs
