appcui 0.4.8

A feature-rich and cross-platform TUI/CUI framework for Rust, enabling modern terminal-based applications on Windows, Linux, and macOS. Includes built-in UI components like buttons, menus, list views, tree views, checkboxes, and more. Perfect for building fast and interactive CLI tools and text-based interfaces.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use super::{ItemBase, ItemStatus, Side};
use crate::graphics::*;
use crate::input::*;
use crate::system::{Handle, RuntimeManager, Theme};
use crate::ui::appbar::events::AppBarEvent;
use crate::ui::appbar::events::ButtonClickEvent;
use crate::utils::Caption;

/// A button in the app bar.
/// 
/// # Examples
/// 
/// ```rust, no_run
/// use appcui::prelude::*;
/// 
/// let button = appbar::Button::new("Button", 0, appbar::Side::Left);
/// ```
pub struct Button {
    receiver_control_handle: Handle<()>,
    caption: Caption,
    tooltip: String,
    pub(super) base: ItemBase,
}

impl Button {
    /// Creates a new button with the specified caption, order and position.
    /// 
    /// # Parameters
    /// 
    /// * `caption` - The caption of the button. If the caption contains the `&` character, the next character (if it is a letter or number) will be set as a hot-key for the button. For example, `"&Save"` will set the hot-key to `Alt+S`.
    /// * `order` - The order of the button (a number that determines the order of the button in the app bar - lower numbers are displayed first from either **left** or **right** depending on the **pos** parameter)
    /// * `pos` - The position of the button (`Left` or `Right`)
    /// 
    /// # Example
    /// 
    /// ```rust, no_run
    /// use appcui::prelude::*;
    /// 
    /// let button = appbar::Button::new("Button", 0, appbar::Side::Left);
    /// ```
    pub fn new(caption: &str, order: u8, pos: Side) -> Self {
        Self::with_tooltip(caption, "", order, pos)
    }
    /// Creates a new button with the specified caption, tooltip, order and position.
    /// 
    /// # Parameters
    /// 
    /// * `caption` - The caption of the button. If the caption contains the `&` character, the next character (if it is a letter or number) will be set as a hot-key for the button. For example, `"&Save"` will set the hot-key to `Alt+S`.
    /// * `tooltip` - The tooltip associated with the button (it will be displayed when the mouse is over the button)
    /// * `order` - The order of the button (a number that determines the order of the button in the app bar - lower numbers are displayed first from either **left** or **right** depending on the **pos** parameter)
    /// * `pos` - The position of the button (`Left` or `Right`)
    /// 
    /// # Example
    /// 
    /// ```rust, no_run
    /// use appcui::prelude::*;
    /// 
    /// let button = appbar::Button::with_tooltip("Button", "Tooltip", 0, appbar::Side::Left);
    /// ```
    pub fn with_tooltip(caption: &str, tooltip: &str, order: u8, pos: Side) -> Self {
        let c = Caption::new(caption, crate::utils::ExtractHotKeyMethod::AltPlusKey);
        let w = c.chars_count() as u8;
        Self {
            receiver_control_handle: Handle::None,
            caption: c,
            tooltip: if tooltip.is_empty() { String::new() } else { tooltip.to_string() },
            base: ItemBase::new(w, order, pos, true),
        }
    }

    /// Returns **true** if the button is enabled, **false** otherwise.
    #[inline(always)]
    pub fn is_enabled(&self) -> bool {
        self.base.is_enabled()
    }

    /// Enables or disables the button.
    #[inline(always)]
    pub fn set_enabled(&mut self, enabled: bool) {
        self.base.set_enabled(enabled);
    }

    /// Returns the caption of the button.
    #[inline(always)]
    pub fn caption(&self) -> &str {
        self.caption.text()
    }

    /// Sets the caption of the button. If the caption contains the `&` character, the next character (if it is a letter or number) will be set as a hot-key for the button. For example, `"&Save"` will set the hot-key to `Alt+S`.
    #[inline(always)]
    pub fn set_caption(&mut self, text: &str) {
        self.caption.set_text(text, crate::utils::ExtractHotKeyMethod::AltPlusKey);
        let w = self.caption.chars_count() as u8;
        self.base.set_width(w);
        self.base.refresh();
    }
    pub(super) fn set_receiver_control_handle(&mut self, handle: Handle<()>) {
        self.receiver_control_handle = handle;
    }
    pub(super) fn paint(&self, surface: &mut Surface, theme: &Theme, status: ItemStatus) {
        let mut format = TextFormatBuilder::new()
            .position(self.base.x(), 0)
            .attribute(status.text_attribute(theme))
            .align(TextAlignment::Left)
            .chars_count(self.caption.chars_count() as u16)
            .build();
        format.set_hotkey_from_caption(status.hotkey_attribute(theme), &self.caption);
        surface.write_text(self.caption.text(), &format);
    }
    pub(super) fn on_execute(&self) {
        RuntimeManager::get().set_appbar_event(AppBarEvent::ButtonClick(ButtonClickEvent {
            button_handle: self.base.handle().cast(),
            control_receiver_handle: self.receiver_control_handle,
        }));
    }
    #[inline(always)]
    pub(super) fn hotkey(&self) -> Key {
        self.caption.hotkey()
    }

    /// Returns the tooltip of the button.
    #[inline(always)]
    pub fn tooltip(&self) -> &str {
        &self.tooltip
    }

    /// Sets the tooltip of the button.
    #[inline(always)]
    pub fn set_tooltip(&mut self, text: &str) {
        if self.tooltip != text {
            self.tooltip.clear();
            self.tooltip.push_str(text);
            self.base.refresh();
        }
    }
}