zng/shortcut_text.rs
1#![cfg(feature = "shortcut_text")]
2
3//! Keyboard shortcut display widget.
4//!
5//! The [`ShortcutText!`] is composite widget that generates localized and styled shortcut *text*, it
6//! can handle all shortcut variations, multiple shortcuts and partially invalid shortcuts.
7//! Extensive configuration is possible using contextual properties that can override.
8//!
9//! The example below demonstrates a basic *key binding editor* that uses the [`ShortcutText!`] widget in multiple places.
10//!
11//! ```
12//! # use zng::focus::{focus_on_init, focusable};
13//! # use zng::gesture::Shortcuts;
14//! # use zng::keyboard::{Key, KeyInputArgs, on_pre_key_down};
15//! # use zng::layout::{align, min_height};
16//! # use zng::prelude::*;
17//! # use zng::shortcut_text::ShortcutText;
18//! #
19//! pub fn shortcut_input(shortcut: Var<Shortcuts>) -> UiNode {
20//! Button! {
21//! // display the shortcut, or the `none_fn` content if there is no shortcut.
22//! child = ShortcutText! {
23//! shortcut = shortcut.clone();
24//! none_fn = wgt_fn!(|_| Text!("no shortcut"));
25//! };
26//! on_click = hn!(|_| {
27//! DIALOG.custom(shortcut_input_dialog(shortcut.clone()));
28//! });
29//! }
30//! }
31//! fn shortcut_input_dialog(output: Var<gesture::Shortcuts>) -> UiNode {
32//! let pressed = var(Shortcuts::new());
33//! let is_valid = var(true);
34//! Container! {
35//! child_top = Wrap!(ui_vec![
36//! Text!("Press the new shortcut and then press "),
37//! ShortcutText!(shortcut!(Enter)), // shortcut text supports inlining
38//! ]);
39//! child_spacing = 20;
40//! // default style is derived from the `font_size` and `font_color` values.
41//! child = ShortcutText! {
42//! shortcut = pressed.clone();
43//! font_size = 3.em();
44//! align = Align::TOP;
45//! when !#{is_valid.clone()} {
46//! font_color = colors::RED;
47//! }
48//! };
49//!
50//! on_pre_key_down = hn!(|args| {
51//! args.propagation().stop();
52//! match &args.key {
53//! Key::Enter => {
54//! let shortcut = pressed.get();
55//! if shortcut.is_empty() || shortcut[0].is_valid() {
56//! is_valid.set(true);
57//! output.set(shortcut);
58//! DIALOG.respond(dialog::Response::ok());
59//! } else {
60//! is_valid.set(false);
61//! }
62//! }
63//! Key::Escape => {
64//! DIALOG.respond(dialog::Response::cancel());
65//! }
66//! _ => {
67//! is_valid.set(true); // clear
68//! pressed.set(args.editing_shortcut().unwrap());
69//! }
70//! }
71//! });
72//! align = Align::CENTER;
73//! min_height = 200;
74//! focusable = true;
75//! focus_on_init = true;
76//! }
77//! }
78//! ```
79//!
80//! [`ShortcutText!`]: struct@ShortcutText
81//!
82//! # Full API
83//!
84//! See [`zng_wgt_shortcut`] for the full widget API.
85
86pub use zng_wgt_shortcut::{
87 ShortcutText, chord_separator_fn, first_n, key_fn, key_gesture_fn, key_gesture_separator_fn, key_txt, keycap, modifier_fn,
88 modifier_txt, panel_fn, shortcut_fn, shortcuts_separator_fn,
89};