zng/
button.rs

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//! # fn example() {
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| {
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//! # fn example() {
52//! # let _ =
53//! Stack!(
54//!     left_to_right,
55//!     5,
56//!     ui_vec![
57//!         // shorthand
58//!         Button!(zng::clipboard::COPY_CMD),
59//!         // cmd with custom child
60//!         Button! {
61//!             cmd = zng::clipboard::PASTE_CMD;
62//!             child = Text!("Custom Label");
63//!         },
64//!     ]
65//! )
66//! # ; }
67//! ```
68//!
69//! The properties a command button sets are documented in the [`cmd`](struct@Button#method.cmd) property docs.
70//! Of particular importance is the [`widget::visibility`], it is set so that the button is only visible if
71//! the command has any handlers, enabled or disabled, this is done because commands are considered irrelevant
72//! in the current context if they don't even have a disabled handler. The example above will only be
73//! visible if you set handlers for those commands.
74//!
75//! ```
76//! # use zng::prelude::*;
77//! # fn example() {
78//! # fn cmd_btn_example() -> UiNode { widget::node::UiNode::nil() }
79//! # let _ =
80//! zng::clipboard::COPY_CMD.on_event(true, hn!(|_| println!("copy"))).perm();
81//! zng::clipboard::PASTE_CMD.on_event(true, hn!(|_| println!("paste"))).perm();
82//! Window! {
83//!     child = cmd_btn_example();
84//! }
85//! # ; }
86//! ```
87//!
88//! [`widget::visibility`]: fn@crate::widget::visibility
89//!
90//! # Style
91//!
92//! The button widget is styleable, the [`style_fn`](fn@style_fn) property can be set in any parent widget or the button
93//! itself to extend or replace the button style.
94//!
95//! ## Base Colors
96//!
97//! The default style derive all colors from the [`base_color`](fn@crate::color::base_color), so if you
98//! only want to change color of buttons you can use this property.
99//!
100//! The example below extends the button style to change the button color to red when it represents
101//! an specific command.
102//!
103//! ```
104//! use zng::prelude::*;
105//! use zng::{button, color::base_color};
106//!
107//! # fn example() { let _ =
108//! Window! {
109//!     button::style_fn = Style! {
110//!         when *#{button::BUTTON.cmd()} == Some(window::cmd::CLOSE_CMD) {
111//!             base_color = color::LightDark {
112//!                 // light theme base
113//!                 light: colors::WHITE.with_alpha(80.pct()).mix_normal(colors::RED),
114//!                 // dark theme base
115//!                 dark: colors::BLACK.with_alpha(80.pct()).mix_normal(colors::RED),
116//!             };
117//!         }
118//!     };
119//! }
120//! # ; }
121//! ```
122//!
123//! # Full API
124//!
125//! See [`zng_wgt_button`] for the full widget API.
126
127pub use zng_wgt_button::{
128    BUTTON, Button, DefaultStyle, LightStyle, LinkStyle, PrimaryStyle, light_style_fn, link_style_fn, primary_style_fn, style_fn,
129};
zng/button.rs

zng/
button.rs
