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
81//!     .on_event(true, true, false, hn!(|_| println!("copy")))
82//!     .perm();
83//! zng::clipboard::PASTE_CMD
84//!     .on_event(true, true, false, hn!(|_| println!("paste")))
85//!     .perm();
86//! Window! {
87//!     child = cmd_btn_example();
88//! }
89//! # ; }
90//! ```
91//!
92//! [`widget::visibility`]: fn@crate::widget::visibility
93//!
94//! # Style
95//!
96//! The button widget is styleable, the [`style_fn`](fn@style_fn) property can be set in any parent widget or the button
97//! itself to extend or replace the button style.
98//!
99//! ## Base Colors
100//!
101//! The default style derive all colors from the [`base_color`](fn@crate::color::base_color), so if you
102//! only want to change color of buttons you can use this property.
103//!
104//! The example below extends the button style to change the button color to red when it represents
105//! an specific command.
106//!
107//! ```
108//! use zng::prelude::*;
109//! use zng::{button, color::base_color};
110//!
111//! # fn example() { let _ =
112//! Window! {
113//!     button::style_fn = Style! {
114//!         when *#{button::BUTTON.cmd()} == Some(window::cmd::CLOSE_CMD) {
115//!             base_color = color::LightDark {
116//!                 // light theme base
117//!                 light: colors::WHITE.with_alpha(80.pct()).mix_normal(colors::RED),
118//!                 // dark theme base
119//!                 dark: colors::BLACK.with_alpha(80.pct()).mix_normal(colors::RED),
120//!             };
121//!         }
122//!     };
123//! }
124//! # ; }
125//! ```
126//!
127//! # Full API
128//!
129//! See [`zng_wgt_button`] for the full widget API.
130
131pub use zng_wgt_button::{
132    BUTTON, Button, DefaultStyle, LightStyle, LinkStyle, PrimaryStyle, light_style_fn, link_style_fn, primary_style_fn, style_fn,
133};
zng/button.rs

zng/
button.rs
