zng/
button.rs

Help
1#![cfg(feature = "button")]
2
3//! Button widget, styles and properties.
4//!
5//! A simple clickable container widget, it can be used by directly handling the click events or by setting it to
6//! operate a [`Command`].
7//!
8//! [`Command`]: crate::event::Command
9//!
10//! # Click Events
11//!
12//! The button widget implements the [`gesture::on_click`] event so you can use it directly, but like any
13//! other widget all events can be set. The example below demonstrates both ways of setting events.
14//!
15//! [`gesture::on_click`]: fn@crate::gesture::on_click
16//!
17//! ```
18//! use zng::prelude::*;
19//!
20//! # let _scope = APP.defaults();
21//! let count = var(0u8);
22//! # let _ =
23//! Button! {
24//!     child = Text!(count.map(|c| match *c {
25//!         0 => Txt::from("Click Me!"),
26//!         1 => Txt::from("Clicked 1 time."),
27//!         n => formatx!("Clicked {n} times."),
28//!     }));
29//!     on_click = hn!(count, |_| {
30//!         count.set(count.get() + 1);
31//!     });
32//!     gesture::on_pre_click = hn!(|args: &gesture::ClickArgs| {
33//!         if count.get() == 10 {
34//!             args.propagation().stop();
35//!             count.set(0u8);
36//!         }
37//!     });
38//! }
39//! # ;
40//! ```
41//!
42//! # Command
43//!
44//! Instead of handling events directly the button widget can be set to represents a command.
45//! If the [`cmd`](struct@Button#method.cmd) property is set the button widget will automatically set properties
46//! from command metadata, you can manually set some of these properties to override the command default.
47//!
48//! ```
49//! use zng::prelude::*;
50//!
51//! # let _scope = APP.defaults();
52//! # let _ =
53//! Stack!(left_to_right, 5, ui_vec![
54//!     // shorthand
55//!     Button!(zng::clipboard::COPY_CMD),
56//!     // cmd with custom child
57//!     Button! {
58//!         cmd = zng::clipboard::PASTE_CMD;
59//!         child = Text!("Custom Label");
60//!     },
61//! ])
62//! # ;
63//! ```
64//!
65//! The properties a command button sets are documented in the [`cmd`](struct@Button#method.cmd) property docs.
66//! Of particular importance is the [`widget::visibility`], it is set so that the button is only visible if
67//! the command has any handlers, enabled or disabled, this is done because commands are considered irrelevant
68//! in the current context if they don't even have a disabled handler. The example above will only be
69//! visible if you set handlers for those commands.
70//!
71//! ```
72//! # use zng::prelude::*;
73//! # let _scope = APP.defaults();
74//! # fn cmd_btn_example() -> impl UiNode { widget::node::NilUiNode }
75//! # let _ =
76//! zng::clipboard::COPY_CMD.on_event(true, app_hn!(|_, _| { println!("copy") })).perm();
77//! zng::clipboard::PASTE_CMD.on_event(true, app_hn!(|_, _| { println!("paste") })).perm();
78//! Window! {
79//!     child = cmd_btn_example();
80//! }
81//! # ;
82//! ```
83//!
84//! [`widget::visibility`]: fn@crate::widget::visibility
85//!
86//! # Style
87//!
88//! The button widget is styleable, the [`style_fn`](fn@style_fn) property can be set in any parent widget or the button
89//! itself to extend or replace the button style.
90//!
91//! ## Base Colors
92//!
93//! The default style derive all colors from the [`base_color`](fn@crate::color::base_color), so if you
94//! only want to change color of buttons you can use this property.
95//!
96//! The example below extends the button style to change the button color to red when it represents
97//! an specific command.
98//!
99//! ```
100//! use zng::prelude::*;
101//! use zng::{button, color::base_color};
102//!
103//! # let _scope = APP.defaults(); let _ =
104//! Window! {
105//!     button::style_fn = Style! {
106//!         when *#{button::BUTTON.cmd()} == Some(window::cmd::CLOSE_CMD) {
107//!             base_color = color::LightDark {
108//!                 // light theme base
109//!                 light: colors::WHITE.with_alpha(80.pct()).mix_normal(colors::RED),
110//!                 // dark theme base
111//!                 dark: colors::BLACK.with_alpha(80.pct()).mix_normal(colors::RED),
112//!             };
113//!         }
114//!     };
115//! }
116//! # ;
117//! ```
118//!
119//! # Full API
120//!
121//! See [`zng_wgt_button`] for the full widget API.
122
123pub use zng_wgt_button::{BUTTON, Button, DefaultStyle, LightStyle, LinkStyle, PrimaryStyle, style_fn};
zng/button.rs

zng/
button.rs
