Command Bar

A command bar is a bar (on the bottom part of a desktop and on top of every window) that contains key associations with commands. All associations are checked first - meaning that if you associate the key F1 with a command, when you press F1 you will not receive the key event, but the command associated with it.

The command bar is unique per application. This means that you need to enable it when a new application is created. A typical way to do this is by using the .command_bar() method when building an application, as in the following snippet:

#![allow(unused)]
fn main() {
let mut app = App::new().command_bar().build()?;
}

Once you have enabled the command bar, you will need to implement CommandBarEvents on your window or custom control, and you will also need to add a list of commands when you create your window and/or custom control. A typical template for this flow looks like this:

#![allow(unused)]
fn main() {
#[Window(events = CommandBarEvents, commands=[Command_1, Command_2 ... Command_n])]
struct MyWin { /* data member */ }
impl MyWin { /* internal methods */ }
impl CommandBarEvents for MyWin {
    fn on_update_commandbar(&self, commandbar: &mut CommandBar) {
        // this is where you add associations (key - command)
        // this can be done via `commandbar.set(...)` method
    }

    fn on_event(&mut self, command_id: mywin::Commands) {
        // this method is called whenever a key from the associated list is being pressed
    }
}
}

It is also important to note that on_update_commandbar is called only if the current focus (or one of its children) has focus. This implies that, except when a modal window is opened, this method will always be called for the desktop object.

Whenever the focus changes, the command bar is cleared and the method on_update_commandbar is invoked again for each control from the focused control up to its oldest ancestor (in most cases, the desktop).

You can always request an update to the command bar by calling the .request_update() method that every control has. This method will force AppCUI to call on_update_commandbar again from the focused control up to its oldest ancestor. Keep in mind that this will not necessarily call on_update_commandbar for the control that calls request_update, unless that control has the focus.

All commands that you add via the commands attribute are automatically added to a module (with the same name as your window or control, but lowercased) under the enum Commands.

Example

The following example shows a window that associates three keys: F1, F2 and F3 to some commands:

use appcui::prelude::*;

#[Window(events = CommandBarEvents, commands=[Help, Save, Load])]
struct MyWin { }
impl MyWin {
    fn new() -> Self {
        Self {
            base: window!("Win,x:1,y:1,w:20,h:7"),
        }
    }
}
impl CommandBarEvents for MyWin {
    fn on_update_commandbar(&self, commandbar: &mut CommandBar) {
        commandbar.set(key!("F1"), "Help", mywin::Commands::Help);
        commandbar.set(key!("F2"), "Save", mywin::Commands::Save);
        commandbar.set(key!("F3"), "Load", mywin::Commands::Load);
    }

    fn on_event(&mut self, command_id: mywin::Commands) {
        match command_id {
            mywin::Commands::Help => {
                // show a help
            },
            mywin::Commands::Save => {
                // save current data
            },
            mywin::Commands::Load => {
                // load something
            },
        }
    }
}

fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().command_bar().build()?;
    a.add_window(MyWin::new());
    a.run();
    Ok(())
}