Getting started

In this chapter we will introduce AppCUI framework and write a first (very simplistic) application in Rust.

What is AppCUI

AppCUI is a cross-platform TUI (Text User Interface / Terminal User Interface) / CUI (Console User Interface) framework designed to allow quick creation TUI/CUI based applications. AppCUI has a lot of out-of-the-box controls (such as buttons, checkboxes, radioboxes, window, tab cotrols, lists, comboboxes, etc), and can also provide quick macros to create custom controls.

The core of AppCUI is written completely in Rust and is designed to be fast and efficient. It is based on a handle-based system, where each control is represented by a handle. This allows for easy manipulation of controls and their properties.

Installation

To install AppCUI just link it directly from cargo.toml as follows:

[dependencies]
appcui = <version>

then you can use the following import in your code:

use appcui::prelude::*;

First Application

Let's start by building a simple window that prints Hello World on the screen.

Firts, make sure that you have the following dependency added in your project cargo.toml file:

[dependencies]
appcui = <version>

Then, replace your main.rs with the following snippet:

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut win = Window::new("First Window", Layout::new("d:c,w:30,h:9"), window::Flags::None);
    win.add(Label::new("Hello World !",Layout::new("d:c,w:13,h:1")));
    app.add_window(win);
    app.run();
    Ok(())
}

or using macros to compact the code:

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut win = window!("'First Window',d:c,w:30,h:9");
    win.add(label!("'Hello World !',d:c,w:13,h:1"));
    app.add_window(win);
    app.run();
    Ok(())
}

After compiling and executing this code you should see something like this:

Remarks: Keep in mind that depending on your terminal and other settings this image might look differently.

Basic Concepts

In this chapter we will discuss about the basic concepts of AppCUI

• Application
• Terminals
• Screen area and sizes
• Surface
• Input

Application

An application in AppCUI is the context that holds all of the framework data together (it keeps all controls, passes messages between controls, manages terminals and system events). There can be only one application per program that uses AppCUI (this is enforced by the framework: subsequenct attempts to create an application will fail).

To create an application three APIs can be used:

1. App::new(). This will create an application and chose the best fit terminal available on the current operating system. The result of new() method is a Builder object that can further be used to configure how the terminal looks like.

2. App::with_backend(backend_type). This will create Builder object, but you will chose the backend to be used instead of having one chosed for you automatically. You can check more on backends availability and types on section Backends

3. App::debug(width, height, script). This is designed to help you with unit testing (see more on this way of initializing AppCUI on section Debug scenarios)

Example (using the default backend):

let mut a = App::new().build().expect("Fail to create an AppCUI application");

Example (using the windows console backend):

let mut a = App::with_backend(apcui::backend::WindowsConsole)
                 .build()
                 .expect("Fail to create an AppCUI application with WindowsConsole backend");

Builder

Using App::new or App::with_backend creates a builder object that can further be used set up how the application will be constructed. For example, you can change the terminal size, colors, font, etc using this object. Keep in mind that not all settings apply for each terminal, and using the wrong configuration might led to an initialization error. Curently, the Builder supports the following methods:

• .size(terminal_size) to set up a terminal size
• .title(terminal_title) to set up a terminal title
• .desktop(custom_desktop) if you want to use a custom desktop instead of the default one
• .single_window() if you want a single window application
• .menu_bar() to enable the application top menu bar
• .command_bar() to enable the application command bar
• .theme(custom_theme) to set up a custom theme or another predefined theme. Read more on themes in section Themes
• .timers_count(count) to set up the number of timers that can be used in the application (if not specified the default value is 4)
• .log_file(path,append) to set up a log file where logs will be displayed. This option will only be valid in debug mode. Once the file was specified, any call to log! macro will be recorded in that file.

After setting up the configuration for an application, just call the build() method to create an application. This methods returns a result of type Result<App,Error> from where the appcui application can be obtained via several methods such as:

• unwrap() or expect(...) methods
• ? opertor
• if let construct

A typical example of using this settings is as follows:

let mut a = App::new().size(Size::new(80,40))       // size should be 80x25 chars
                      .menu_bar()                   // top menu bar should be enabled
                      .command_bar()                // command bar should be enabled
                      .log_file("debug.log", false) // log into debug.log
                      .build()
                      .expect("Fail to create an AppCUI application");

Errors

If the .build() method from the Builder object fails, an error is returned. You can use .kind member to identify the type of error. Curently, the following error class are provided:

• ErrorKind::InitializationFailure a failure occured when initializing the backend API (this is usually due to some OS constranits).
• ErrorKind::InvalidFeature an invalid feature (configuration option) that is not compatible with the current terminal was used. For example, an attemp to set up DirectX for NCurses backend will be invalid.
• ErrorKind::InvalidParameter a valid feature but with invalid parameters was used. For example, an attempt to instantiate a terminal with the size of (0x0) will trigger such an error.

To get a more detailed description of the Error, use the description() method from class Error just like in the next code snipped:

let result = App::new().size(Size::new(0,0)).build();
if let Err(error) = result {
    // we have an Error - let's print it
    println!("Fail to instantiate AppCUI");
    println!("Error: {}",error.description());
}

Execution flows

Usually, each AppCUI program consists in the following steps:

1. create an application
2. add on or multiple windows to that application (to do this use the add_window method from struct App)
3. run the application via method run. This method consumes the object and as such you can not use the application anymore after this method ends.

A typical main.rs file that uses AppCUI framework looks like this:

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    // 1. build an application
    let mut app = App::new().build()?;
    // 2. add one or several windows
    app.add_window(/* a window */);
    // 3. run the aplication
    app.run();
    Ok(())
}

Debug scenarios

When using AppCUI and needing to test the interface, it is recommended to write the unit tests using App::debug(...) method. This method allows one to write a succesion of system events (mouse clicks, keys being pressed, etc) and validate if the output is the expected one. This succesion of command is considered an event script - form out of multiple commands, each command written on a line. A command can have parameters. You can also use // to comment a command.

General format for a script

Command-1(param1,param2,param3)
Command-2()
// comment

Remarks:

• App::debug(...) will panic if the script is incorect (a command is not valid, the number of parameters is incorect, etc).
• AppCUI allows only one instance at one time (this is done via a mutex object). If you have multiple unit test and you try to run them with cargo test command, you might get an error as cargo might try to use multiple threads to do this and it is likely that one thread might try to start an AppCUI application while another one is already running on another thread. The solution in this case is to run the tests using a single thread:

cargo test -- --test-threads=1

Mouse related commands

Mouse related commands are a set of commands that simulate various mouse events

Keyboard related commands

Usually the key parameter can have several forms:

• key
• modifier-1+key
• modifier-1+modifier-2+key
• modifier-1+modifier-2+modifier-3+key

where the list of all keys supported by this command is:

• F-commands (F1 to F12)
• Letters (A to Z) - with upper case
• Numbers (0 to 9)
• Arrows (Up, Down, Left, Right)
• Navigation keys (PageUp, PageDown, Home, End)
• Deletion and Insertions (Delete , Backspace, Insert)
• White-spaces (Space, Tab)
• Other (Enter, Escape)

and the list of modifiers consists in Shift, Ctrl and Alt.

Paint related commands

System events

Clipboard commands

Validation commands

Example

Let's consider a scenario where we want to test if moving a window with a mouse works as expected. For this we will create a test function, with the following code:

#[test]
fn check_if_window_can_be_moved() {
    let script = "
        Paint('initial state')
        CheckHash(0xB1471A30B30F5C6C)
        Mouse.Drag(30,3,35,5)
        Paint('window was moved')
        CheckHash(0x419533D4BBEFE538)
    ";
    let mut a = App::debug(60, 10, script).build().unwrap();
    let w = Window::new("Title", Layout::new("d:c,w:20,h:5"), window::Flags::None);
    a.add_window(w);
    a.run();
}

Let's break the event script in pieces and see exactly what is supposed to happen:

1. Paint('initial state') - this will print the virtual screen. It should look like the following (but with colors):

    +===================================================================+
    | Name  : initial state                                             |
    | Hash  : 0xB1471A30B30F5C6C                                        |
    | Cursor: Hidden                                                      |
    | ------------------------------------------------------------------- |
    |                                                                     | 11111111112222222222333333333344444444445555555555           |
    |                                                                     | 012345678901234567890123456789012345678901234567890123456789 |
    | ------------------------------------------------------------------- |
    | 0                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 1                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 2                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 3                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╔════ Title ════[x]╗▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 4                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 5                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 6                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 7                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╚══════════════════╝▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 8                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 9                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | ------------------------------------------------------------------- |

We can inspect inspect if the position of the window is correct. We can also notice the hash compited for the entire virtual screen: 0xB1471A30B30F5C6C (this could help us do further checks).

2. CheckHash(0xB1471A30B30F5C6C) - this compute the hash for the entire virtual screen and then check it againts the expected one. The usual scenario here is that we firs apply a Paint command, validate it, and them write the CheckHash command with the hash obtained from the Paint command. This way, if something changes to the logic/code of the program, the new hash will be different. If the hash for the virtual screen is not as expected the application will panic. If used in a test, this behavior will fail the test.

3. Mouse.Drag(30,3,35,5) this command does the following:

   • moves the mouse to the (30,3) coordonate (over the title of the window)
   • click and hold the left mouse button
   • moves the mouse to a new position (35,5) (since we hold the mouse button, we expect the window to move as well)
   • releases the left mouse button

4. Paint('window was moved') now we should see something like the following. Notice that indeed, the window was moved to a new position. We also have a new hash for the virtual screen: 0x419533D4BBEFE538

    +===================================================================+
    | Name  : window was moved                                          |
    | Hash  : 0x419533D4BBEFE538                                        |
    | Cursor: Hidden                                                      |
    | ------------------------------------------------------------------- |
    |                                                                     | 11111111112222222222333333333344444444445555555555           |
    |                                                                     | 012345678901234567890123456789012345678901234567890123456789 |
    | ------------------------------------------------------------------- |
    | 0                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 1                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 2                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 3                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 4                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 5                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╔════ Title ════[x]╗▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 6                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 7                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 8                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 9                                                                   | ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╚══════════════════╝▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | ------------------------------------------------------------------- |

25. CheckHash(0x419533D4BBEFE538) - finally we check the new hash to see if it maches the one we expect.

Remark: using unit tests (while it works with the Paint command activated) might look strange on the actual screen (especially if all you need is to validate an example). As such, it is best that after one example such as the previous one was validated, to add another command at the begining of the script: Paint.Enable(false). This will not change the logic of the script, instead it will not print anything on the screen. As such, the final test function should look like this:

use appcui::prelude::*;

#[test]
fn check_if_window_can_be_moved() {
    let script = "
        Paint.Enable(false)
        Paint('initial state')
        CheckHash(0xB1471A30B30F5C6C)
        Mouse.Drag(30,3,35,5)
        Paint('window was moved')
        CheckHash(0x419533D4BBEFE538)
    ";
    let mut a = App::debug(60, 10, script).build().unwrap();
    let w = Window::new("Title", Layout::new("d:c,w:20,h:5"), window::Flags::None);
    a.add_window(w);
    a.run();
}

and its execution should produce an output similar to the next one:

running 1 test
test check_if_window_can_be_moved ... ok

Recording Events

Writing complex debug or unit-test scenarios might be a tedious task. However, it can be automated with the record events feature from AppCUI.

The first thing is to enable this feature (via cargo.toml) where you need to enable the feature EVENT_RECORDER for default building, like in the following snipped.

[features]
default = ["EVENT_RECORDER"]
DEBUG_SHOW_WINDOW_TITLE_BOUNDERIES = []
EVENT_RECORDER = []

Once you do this, any program that uses AppCUI will enable a special hotkey Ctrl+Alt+Space that will allow you to open a special configuration window similar to the one from the next image:

You can use this window to perform the following action:

1. Add a new state (by typeing its name and pressing Enter) - this wil efectivelly add a new Paint and ChackHash commands
2. Enable automated mode (via shortkey F9). Enabling auto record mode will efectively check whenever the screen changes because of the action performed and automatiicaly add a Paint and CheckHash commands. It will also filter out all other raw events (related to key strokes and mouse).
3. Clear all events recorded up to this moment (via hotket F8)

The tipical way of using this feature is as follows:

• enable the feature from cargo.toml
• run you application
• if you prefer to do this manually, perform certain action that change the state of the application, then press Ctrl+Alt+Space and in the configuration menu type the name of the new state and hit Enter.
• if you prefer automated mode, press Ctrl+Alt+Space and enable automatic mode via F9 short key.
• Once you finish doing your scenario, exit the application. At that point a file named events.txt will be dropped near your application. You can use its content as part of a unit test or for debug purposes.

Logging

AppCUI supports an internal logging mechanism that can be used to log messages to a file. The logging mechanism is available only in debug mode and can be used by calling the log! macro. The macro has the following syntax:

log!(TAG, format, ...)

To enable the logging mechanism, you need to specify a log file when creating the application. This can be done by calling the log_file method when AppCUI is initialized This method has two parameters: the path to the log file and a boolean value that specifies if the log file should be appended or overwritten.

AppCUI::new().log_file("debug.log", false)
             .build()
             .expect("Fail to create an AppCUI application");

Example

let x = 10;
log!("INFO", "The value of x is: {}", x);

Logging mechanism has zero overhead when the application is compiled in release mode. The logging mechanism is disabled in release mode and the log! macro will not generate any code.

Screen area and sizes

The screen in AppCUI is a 2D matrix of characters, with different widths (w) and heights (h).

It is important to note that each character is going to have the same size. For each character we have the following attributes:

• Forenground color (the color of the character that we are printing)
• Background color (the color of the character background)
• Attributes: Bold, Italic, Underline, Boxed

The following collors are supported by AppCUI via Color enum from AppCUI::graphics module:

Besides this list, a special enuma variant Color::Transparent can be used to draw without a color (or in simple terms to keep the existing color). For example, if the current character has a forenground color Red writing another character on the same position with color Transparent will keep the color Red for the character.

Additionally, if the TRUE_COLORS feature is enabled, the following variant is supported:

• Color::RGB(r, g, b) - this is a custom color that is defined by the RGB values.

REMARKS:

1. Not all terminals support this exact set of colors. Further more, some terminals might allow changing the RGB color for certain colors in the pallete.
2. Enabling TRUE_COLORS feature does not mean that the terminal supports 24-bit colors. It only means that the AppCUI framework will use 24-bit colors for the screen, but the terminal might still need to convert them to the terminal's color pallete.
3. Enabling TRUE_COLORS feature will make the size of the Color enum to be 4 bytes (instead of 1 byte without this feature). If memory is a concern and you don't need true colors, it is recommended to NOT enable this feature.

The list of attributes available in AppCUI are described by CharFlags enum from AppCUI::graphics module and include the following flags:

• Bold - bolded character
• Underline - underlined character
• Italic - italic character

These flags can be used with | operator if you want to combine them. For example: CharFlags::Bold | CharFlags::Underline means a character that is both bolded and underlined.

Character

As previously explained, a character is the basic unit of AppCUI (we can say that it is similar to what a pixel is for a regular UX system). The following method can be used to build a character:

#![allow(unused)]
fn main() {
pub fn new<T>(code: T, fore: Color, back: Color, flags: CharFlags) -> Character
}

where:

• fore and back are characters colors (foreground and background)
• code can be a character (like 'a' or 'b') or a value of type SpecialCharacter that can be used to quickly access special characters (like arrows). Any type of UTF-8 character is allowed.
• flags are a set of flags (like Bold, Underline, ...) that can be used.

The list of all special characters that are supported by AppCUI (as described in the SpacialCharacter enum) are:

Box lines and corners

Arrows

Blocks

Other

Other character constructors

Besides Character::new(...) the following constructors are also available:

1. #![allow(unused)]
   fn main() {
    pub fn with_char<T>(code: T) -> Character
   }

   this is the same as calling:

   #![allow(unused)]
   fn main() {
   Character::new(code, Color::Transparent, Color::Transparent, CharFlags::None)
   }

2. #![allow(unused)]
   fn main() {
    pub fn with_color(fore: Color, back: Color) -> Character
   }

   this is the same as calling:

   #![allow(unused)]
   fn main() {
   Character::new(0, fore, fore, CharFlags::None)
   }

   Note: Using the character with code 0 means keeping the existing character but chainging the colors and attributes.

Macro builds

You can also use char! macro to quickly create a character. The macro supports tha following positional and named parameters:

and the named parameters:

The following values can be used as color parameters for foreground and background parameters:

For Transparent color you can use the following values: transparent, invisible or ?.

You can also specify special characters by either using their specific name from the enum SpecialChars or by using certaing adnotations as presented in the following table:

Character attributes

Sometimes, you might want to use a character with a specific color and attributes. For example, you might want to use a bolded character with a red color on a yellow background. This is in particular useful when building a theme where you just select the attributes and colors and then apply them to the characters. AppCUI provides a specific structure called CharAttribute that allows you to define colors and attributes for a character. To create a CharAttribute you can use the following methods:

#![allow(unused)]
fn main() {
impl CharAttribute {
    pub fn new(fore: Color, back: Color, flags: CharFlags) -> CharAttribute {...}
    pub fn with_color(fore: Color, back: Color) -> CharAttribute {...}
    pub fn with_fore_color(fore: Color) -> CharAttribute {...}
    pub fn with_back_color(back: Color) -> CharAttribute {...}
}
}

or the macro charattr! that works similar to char! but it returns a CharAttribute object. The macro supports tha following positional and named parameters:

and the named parameters:

Examples

Example 1: Letter A with a Red color on an Yellow background:

#![allow(unused)]
fn main() {
Character::new('A',Color::Red,Color::Yellow,CharFlags::None)
}

or

char!("A,red,yellow")

or

char!("A,r,y")

Example 2: Letter A (bolded and underlined) with a White color on a Dark blue background:

#![allow(unused)]
fn main() {
Character::new('A',Color::White,Color::DarkBlue,CharFlags::Bold | CharFlags::Underline)
}

or

char!("A,fore=White,back=DarkBlue,attr=[Bold,Underline]")

or

char!("A,w,db,attr=Bold+Underline")

Example 3: An arrow towards left a Red color while keeping the current background:

#![allow(unused)]
fn main() {
Character::new(SpecialCharacter::ArrowLeft,Color::Red,Color::Transparent,CharFlags::None)
}

or

char!("ArrowLeft,fore=Red,back=Transparent")

or

char!("<-,red")

or

char!("<-,r")

Example 4: An arrow towards left a DarkGreen color, Bolded and Underlined while keeping the current background. We will use a CharAttribute for this example:

#![allow(unused)]
fn main() {
let attr = CharAttribute::new(Color::DarkGreen,Color::Transparent,CharFlags::Bold | CharFlags::Underline);  
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr);
}

or

let attr = charattr!("DarkGreen,Transparent,attr:Bold+Underline");
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr));

or

let attr = charattr!("dg,?,attr:Bold+Underline");
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr);

Surface

A surface is a two-dimensional array of Characters that can be displayed on the screen. It is the basic building block of the UI system. Surfaces can be created and manipulated using the Surface class.

A surface has the following properties:

• a clipper area that restricts the drawing operations to a specific region of the surface
• an origin point that is used as the reference point for all drawing operations
• a cursor (that can be moved, enabled or disabled)
• an array (vector) of characters that represent the content of the surface

Remarks: A screen is in fact a surface that covers the entire console visible space and it is created automatically when the application starts.

Creating a Surface

To create a new surface, you can use the method Surface::new() - with two parameters, width and height - that returns a new surface with the specified dimensions. Both width and height must be greater than zero and smaller than 10000. Any value outside this range will be clamped to the nearest valid value.

The surface will be filled with the space character ' ' with a White foreground and Black background. The surface will have the origin set to (0,0) and the clip area will be the entire surface. The cursor associated with the surface will be disabled.

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
}

Remarks: Creating a surface is rarely needed, as the library will create the main screen surface automatically when the application starts and will provide a mutable reference to that surface whenever the on_paint event is called for a control.

Clip Area and Origin point

Every surface has a clip area and an origin point. The clip area restricts the drawing operations to a specific region of the surface. The origin point is used as the reference point for all drawing operations.

For example, if the clip area is set to (10,10,20,20) and the origin point is set to (5,5), then the drawing operations will be restricted to the area (15,15,25,25) of the surface.

The following methods can be used to manipulate the clip area and the origin point of a surface:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
// Set the origin point to (10,10)
surface.set_origin(10, 10);
// Set the clip area to (10,10,20,20)
surface.set_clip(10, 10, 20, 20);
// draw a border around the clip area
surface.draw_rect(
    Rect::new(0,0,9,9), // left,top,right,bottom relativ to origin
    LineType::Single,
    CharAttribute::with_color(Color::White, Color::DarkRed)
);
// reduce the clip area by 1 character on each side
// so that we will not draw over the border
surface.reduce_clip_by(1, 1, 1, 1);
// draw something else
// ...

/// finally, reset the clip area and origin point
/// to the entire surface
surface.reset_clip();
surface.reset_origin();
}

Cursor

Every surface has an associated cursor that can be moved, enabled or disabled. The cursor is used to indicate the current position where the next character will be drawn. Depending on the terminal, the cursor can be a blinking rectangle, a blinking underline or a blinking vertical line.

The following methods can be used to manipulate the clip area and the origin point of a surface:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface};

let mut surface = Surface::new(100, 50);
surface.set_cursor(10, 10);
}

Drawing characters on a Surface

The most basic operation that can be performed on a surface is drawing a character at a specific position. This allows for more complex operations like drawing text, lines, rectangles, etc. to be built on top of it.

A surface has the following methods that can be used to manipulate characters and how they are drown on the surface:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
// Set the origin point to (10,10)
surface.set_origin(10, 10);
// Set the clip area to (10,10,20,20)
surface.set_clip(10, 10, 20, 20);
// Clear the clip area
surface.clear(Character::new('*', Color::Silver, Color::Black, CharFlags::None))
// write a character at position (5,5) relativ to the origin
// point (10,10) => the character will be drawn at position (15,15)
surface.write_char(5, 5, Character::new('A', Color::Yellow, Color::DarkBlue, CharFlags::None));
}

Lines

Drawing lines is a common operation when building a UI. In AppCUI there are two methods that cen be used to draw lines (vertical and horizontal) on a surface.

• use special characters to draw the line (like single lines, double lines, etc) that are designed to be used in this context
• use a generic character to draw the line

Using special characters to draw lines

The following methods can be used to draw lines on a surface using special characters:

These methods take a parameter line_type that specifies the type of line that will be drawn. The line type can be one of the following values:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, LineType, CharAttribute, Color};

let mut surface = Surface::new(100, 50);
surface.draw_vertical_line(10, 10, 20, 
                            LineType::Single, 
                            CharAttribute::with_color(Color::White, Color::Black));
}

Using a generic character to draw lines

The following methods can be used to draw lines on a surface using a generic character:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, CharAttribute, Color, Character};

let mut surface = Surface::new(100, 50);
let c = Character::new('=', Color::White, Color::Black, CharFlags::None);
surface.fill_horizontal_line(10, 10, 20, c);
}

Rectangles

Rectangles are the most basic shape you can draw on a surface. They are defined by a position and a size. The position is the top-left corner of the rectangle, and the size is the width and height of the rectangle.

In AppCUI a rectangle is defined based on the following structure:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, Debug)]
pub struct Rect {
    left: i32,
    top: i32,
    right: i32,
    bottom: i32,
}
}

A rectangle can be created using the following methods:

1. Rect::new(left, top, right, bottom) - creates a new rectangle based on the provided coordinates.
2. Rect::with_size(left, top, width, height) - creates a new rectangle based on the provided position and size.
3. Rect::with_alignament(x, y, width, height, align) - creates a new rectangle based on the provided position, size and alignment.
4. Rect::with_point_and_size(point, size) - creates a new rectangle based on the provided point and size.

The alignament in the third method is defined as follows:

#![allow(unused)]
fn main() {
#[repr(u8)]
#[derive(Copy, Clone, PartialEq, Debug)]
pub enum Alignament {
    TopLeft = 0,
    Top,
    TopRight,
    Right,
    BottomRight,
    Bottom,
    BottomLeft,
    Left,
    Center,
}
}

Alignament	Decription	Preview
TopLeft	(X,Y) represents the top-left corner of the rectangle
Top	(X,Y) represents the top-center of the rectangle
TopRight	(X,Y) represents the top-right corner of the rectangle
Right	(X,Y) represents the right-center of the rectangle
BottomRight	(X,Y) represents the bottom-right corner of the rectangle
Bottom	(X,Y) represents the bottom-center of the rectangle
BottomLeft	(X,Y) represents the bottom-left corner of the rectangle
Left	(X,Y) represents the left-center of the rectangle
Center	(X,Y) represents the center of the rectangle

To draw a rectangle on a surface, you can use the following methods:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
let r = Rect::new(10, 10, 20, 20);
// fill the rectangel with spaces (dark blue background)
surface.fill_rect(r, Character::new(' ', Color::White, Color::DarkBlue, CharFlags::None));
// draw a border around the rectangle (white on black)
surface.draw_rect(r, LineType::Single, CharAttribute::with_color(Color::White, Color::Black));
}

Text

Writing text on a surface is a common task in GUI programming, that can be achieved using the following methods:

1. write_string(...) - writes a string (String or &str) on the surface starting from a specific position, color and character attribute.
2. write_ascii(...) - similar to write_string, but it writes only ASCII characters.
3. write_text(...) - a more complex method that allows alignament, wrapping and text formatting.

Write a string

The write_string(...) method writes a string on the surface starting from a specific position. The method has the following signature:

#![allow(unused)]
fn main() {
pub fn write_string(&mut self, 
                    x: i32, 
                    y: i32, 
                    text: &str, 
                    attr: CharAttribute, 
                    multi_line: bool)
}

The multi-line parameter specifices if the text should interpret new line characters as a new line or not. if set to false the code of this method is optimized to write the text faster. The text will be written from left to right, starting from the specified position (x,y).

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, CharAttribute, Color};

let mut surface = Surface::new(100, 50);
surface.write_string(10, 10, 
                    "Hello World!", 
                    CharAttribute::with_color(Color::White, Color::Black), 
                    false);
}

Write an ASCII string

The write_ascii(...) method writes an ASCII string on the surface starting from a specific position. The method has the following signature:

#![allow(unused)]
fn main() {
pub fn write_ascii(&mut self, 
                   x:i32, 
                   y:i32, 
                   ascii_buffer: &[u8], 
                   attr: CharAttribute, 
                   multi_line: bool)
}

The multi-line parameter specifices if the text should interpret new line characters as a new line or not. if set to false the code of this method is optimized to write the text faster. The text will be written from left to right, starting from the specified position (x,y).

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, CharAttribute, Color};

let mut surface = Surface::new(100, 50);
surface.write_ascii(10, 10,
                   b"Hello World!",
                   CharAttribute::with_color(Color::White, Color::Black),
                   false);
}

Write a formatted text

In some cases, you may need to write a text that is formatted in a specific way (like alignament, wrapping, etc). The write_text(...) method allows you to do this. The method has the following signature:

#![allow(unused)]
fn main() {
pub fn write_text(&mut self, text: &str, format: &TextFormat)
}

where the TextFormat structure can be created using the TextFormatBuilder in the following way:

Example:

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, CharAttribute, Color, TextFormatBuilder, WrapType};
let format = TextFormatBuilder::new()
    .position(10, 10)
    .attribute(CharAttribute::with_color(Color::White, Color::Black))
    .align(Alignment::Center)
    .wrap_type(WrapType::Word(20))
    .build();
surface.write_text("Hello World!", &format);
}

Once a TextFormat object is created, you can modify it and use it using the following methods:

The WrapType enum is defined as follows:

#![allow(unused)]
fn main() {
pub enum WrapType {
    WordWrap(u16),
    CharacterWrap(u16),
    MultiLine,
    SingleLine,
    SingleLineWrap(u16),
}
}

with the following meaning:

Let's consider the following string Hello World!\nFrom AppCUI. This text will be printed as follows:

Images

While AppCUI is developed for CLI usage, it can still use images to some degree, meaning that it can store an images as an array of pixels and it has various methods to represent it using characters and combination of existing colors.

To create an image, use the class Image with the following construction methods:

1. Image::new(width,height) creates an image with a specific size. That image will be filled with a transparent pixel that you can later change
2. Image::with_str(...) creates a 16 color image based on a string representation.

Methods

Once an image is create you can use the following methods to manipulate it:

Pixel

A pixel is a simple structure defined as follows:

#[derive(Copy, Clone, Debug, PartialEq, Default)]
pub struct Pixel {
    pub red: u8,
    pub green: u8,
    pub blue: u8,
    pub alpha: u8,
}

You can create a pixel in the following way:

1. using direct construction:

   let px = Pixel { red:10, green: 20, blue:30, alpha: 255 };
   

2. using the .new(...) constructor:

   let px = Pixel::new(10, 20, 30, 255);
   

3. using the .with_rgb(...) constructor:

   let px = Pixel::with_rgb(10, 20, 30);
   

4. using the .with_color(...) constructor:

   let px = Pixel::with_color(Color::Aqua);
   

5. using the From implementation from an u32 (in an ARGB format - Alpha Red Green Blue).

   let px = Pixel::from(0xFF005090u32);
   

6. using the Default implementation (this will create a trnsparent pixel where Red=0, Green=0, Blue=0 and Alpha=0)

   let px = Pixel::default();
   

Usage

A typical way to create an image is as follows:

1. create a new Image object
2. optionally, fill the entire image with a differnt pixel than the default one
3. use .set_pixel(...) method to fill the image. At this point aditional crates that can load an image from a file can be used to transfer the content of that image into this object.

The following example draws a horizontal Red line on a Blue background image of size 32x32:

let mut img = Image::new(32,32);
img.clear(Pixel::with_color(Color::Blue));
for i in 5..30 {
    img.set_pixel(i,10,Pixel::with_color(Color::Red));
}

Building from a string

A more common usage is to build a small image from a string that specifies colors for each pixel. The format in this case is as follows:

• each line is enclosed between two characters |
• outside of these characters any other character is being ignored (usually you add spaces or new lines to align the text)
• each line must have the same with (in terms of the number of characters that are located between | characters )

for example, a 5x5 image will be represented as follows:

let string_representation = r#"
      |.....|
      |.....|
      |.....|
      |.....|
      |.....|
"#;

Within the space between the characters | the following characters have the a color association:

So ... to create an image of a red heart ♥ you will need to create the folowing string:

let heart = r#"
    |..rr.rr..|
    |.rrrrrrr.|
    |.rrrrrrr.|
    |..rrrrr..|
    |...rrr...|
    |....r....|
"#;
let img = Image::with_str(heart);

Rendering images

AppCUI framework relies on characters. As such, an image can not be displayes as it is. However, there is one method in the Surface object that be used to aproximate an image:

impl Surface {
    // other methods
    pub fn draw_image(&mut self, x: i32, 
                                y: i32, 
                                image: &Image, 
                                rendering_method: image::RendererType, 
                                scale_method: image::Scale
                    ) { ... }
}

This method attempts to draw an image using characters and the available colors. The following rendering methods are available:

• SmallBlocks
• LargeBlocks64Colors
• GrayScale
• AsciiArt

Let's consider an image of Cuddly Ferris and see how it will be displayed using different rendering methods:

Methods	Result
SmallBlocks
LargeBlocks64Colors
GrayScale
AsciiArt

The supported scales (from the enume image::Scale):

• Scale::NoScale => 100%
• Scale::Scale50 => 50%
• Scale::Scale33 => 33%
• Scale::Scale25 => 25%
• Scale::Scale20 => 20%
• Scale::Scale10 => 10%
• Scale::Scale5 => 5%

Input

AppCUI allows input from:

• Keyboard
• Mouse

The input is received via OnKeyPressed and OnMouseEvents traits and they are usually used when designing a Custom Control.

Mouse

Mouse events are received through the trait OnMouseEvent defined as follows:

pub trait OnMouseEvent {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

where MouseEvent is defined as follows:

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum MouseEvent {
    Enter,
    Leave,
    Over(Point),
    Pressed(MouseEventData),
    Released(MouseEventData),
    DoubleClick(MouseEventData),
    Drag(MouseEventData),
    Wheel(MouseWheelDirection)
}

where MouseEventData is defined as follows:

#[derive(Copy, Clone, Debug, PartialEq)]
pub struct MouseEventData {
    pub x: i32,
    pub y: i32,
    pub button: MouseButton,
    pub modifier: KeyModifier
}

and MouseButton is an enum with the following values:

• Left - indicates that the left mouse button was pressed
• Right - indicates that the right mouse button was pressed
• Center - indicates that the center mouse button was pressed
• None - indicates that no button was pressed

MouseWheelDirection is an enum with the following values:

• Up - indicates that the mouse wheel was rotated up
• Down - indicates that the mouse wheel was rotated down
• Left - indicates that the mouse wheel was rotated left
• Right - indicates that the mouse wheel was rotated right
• None - indicates that the mouse wheel was not rotated

These events are reflect the following actions:

• MouseEvent::Enter - the mouse cursor entered the control
• MouseEvent::Leave - the mouse cursor left the control
• MouseEvent::Over(Point) - the mouse cursor was moved over the control and it is now at a the specified point
• MouseEvent::Pressed(MouseEventData) - a mouse button was pressed over the control
• MouseEvent::Released(MouseEventData) - a mouse button was released. If a mouse button was pressed over the control and the control can receive input, then all of the following mouse events will be send to the control (even if the mouse cursor is outside the control) until the mouse button is released.
• MouseEvent::DoubleClick(MouseEventData) - a mouse button was double clicked over the control
• MouseEvent::Drag(MouseEventData) - a mouse button was pressed over the control and the mouse cursor was moved while keeping the button pressed
• MouseEvent::Wheel(MouseWheelDirection) - the mouse wheel was rotated

Usage

The events are generated by the system and are sent to the control that has the focus. The control can choose to ignore the event or to process it. The OnMouseEvent trait is usually used when designing a Custom Control.

A typical implementation of the OnMouseEvent trait looks like this:

impl OnMouseEvent for <MyControl> {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        // check the key
        match event {
            MouseEvent::Enter => {
                // the mouse cursor entered the control
            },
            MouseEvent::Leave => {
                // the mouse cursor left the control
            },
            MouseEvent::Over(point) => {
                // the mouse cursor is over the control
            },
            MouseEvent::Pressed(data) => {
                // a mouse button was pressed over the control
            },
            MouseEvent::Released(data) => {
                // a mouse button was released over the control
            },
            MouseEvent::DoubleClick(data) => {
                // a mouse button was double clicked over the control
            },
            MouseEvent::Drag(data) => {
                // a mouse button was pressed over the control and the mouse cursor was moved while keeping the button pressed
            },
            MouseEvent::Wheel(direction) => {
                // the mouse wheel was rotated
            }
        }
    }
}

Key modifiers

The MouseEventData structure contains a modifier field that indicates the key modifiers that were pressed when the mouse event occurred. This can be used to perform different actions based on the key modifiers (e.g., pressing Ctrl while clicking the mouse button can have a different effect than just clicking the mouse button).

impl OnMouseEvent for <MyControl> {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        match event {
            MouseEvent::Drag(data) => {
                if data.modifier.contains(KeyModifier::Ctrl) {
                    // the mouse button was pressed while the Ctrl key was also pressed
                } else {
                    // the mouse button was pressed without the Ctrl key being pressed 
                }
            },
            _ => {
                EventProcessStatus::Ignored
            }
        }
    }
}

Keyboard

Keyboard events are received through the trait OnKeyPressed defined as follows:

pub trait OnKeyPressed {
    fn on_key_pressed(&mut self, key: Key, character: char) -> EventProcessStatus {
        // do something depending on the key pressed
    }
}

This method has two parameters:

1. the key parameter (that provides information about the code of the key that was pressed and its modifiers)
2. the character (when this is the case). This is usually when you want insert text intro a control (for example in case of a TextField)

Key

A key in AppCUI is defined as follows:

#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Key {
    pub code: KeyCode,
    pub modifier: KeyModifier,
}

where:

• code is an enum that indicates a code for the key that was pressed and it includes:
  • F-commands (F1 to F12)
  • Letters (A to Z) - with apper case
  • Numbers (0 to 9)
  • Arrows (Up, Down, Left, Right)
  • Navigation keys (PageUp, PageDown, Home, End)
  • Deletion and Insertions (Delete , Backspace, Insert)
  • White-spaces (Space, Tab)
  • Other (Enter, Escape)
• modifier can be one of the following (including combination between them):
  • Shift
  • Ctrl
  • Alt

The crete a key use:

1. Key::new(code, modifier) - for example:

   let k = Key::new(KeyCode::F1,KeyModifier::Alt | KeyModifier::Ctrl);
   let k2 = Key::new(KeyCode::Enter, KeyModifier::None);
   

2. using From implementation:

   let k = Key::from(KeyCode::F1);
   // this is equivalent to Key::new(KeyCode::F1, KeyModifier::None);
   

3. key! macro - this can be used to create a key:

   let k1 = key!("F2");
   let k2 = key!("Enter")
   let k3 = key!("Alt+F4")
   let k4 = key!("Ctrl+Alt+F")
   let k5 = key!("Ctrl+Shift+Alt+Tab")
   

Usage

The usual usage is via OnKeyPressed::on_key_pressed(...) method as follows:

impl OnKeyPressed for <MyControl> {
    fn on_key_pressed(&mut self, key: Key, character: char) -> EventProcessStatus {
        // check the key
        match key.value() {
            // check various key combinations
        }
        // check the character
        match character {
            // do something with the character
        }
        
        EventProcessStatus::Ignored
    }
}

The following example checks the arrow keys for movement and ignores the rest of the keys:

impl OnKeyPressed for <MyControl> {
    fn on_key_pressed(&mut self, key: Key, character: char) -> EventProcessStatus {
        match key.value() {
            key!("Left") => { 
                /* move left */ 
                return EventProcessStatus::Processed;
            }
            key!("Right") => { 
                /* move right */ 
                return EventProcessStatus::Processed;
            }
            key!("Ctrl+Left") => { 
                /* Move to begining */ 
                return EventProcessStatus::Processed;
            }
            key!("Ctrl+Right") => { 
                /* Move to end */ 
                return EventProcessStatus::Processed;
            }
            _ => {
                return EventProcessStatus::Ignored;
            }
        }
    }
}

Clipboard

Access to clipboard can be done via a special non-instantiable class called Clipboard. This class provides the basic functionality to work with the clipboard, as follows:

Access to clipboard depends on the type of backend you are using (e.g. WindowsConsole backend relies on low level APIs like OpenClipboard, GetClipboardData, EmptyClipboard, SetClipboardData and CloseClipboard). As such, you will only be able to use this class after the application has been initialized (e.g. after a call to App::new()). Calling static methods from this class before that moment will have no action.

Example

A typical example on how to use the clipboard looks like the following:

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    // fist initialize the application
    let mut a = App::new().build()?;
    // now use the clipboard
    if let Some(text) = Clipboard::text() {
        // do something with the text from the clipboard
    }
    // now set a new text into the clipboard:
    Clipboard::set_text("Hello world");
    Ok(())
}

Remarks: Keep in mind that calling Clipboard::text() will always create a String object containing the content of the clipboad. If you just want to check if something exists in a clipboard (for example to enable/disable some menu items - use Clipboard::has_text() method instead).

Limitations

Depending on the type of terminal, the clipboard comes with some limitations (for example in case of WindowsConsole backend, the clipboard can not store unicode characters that are not in WTF-16 format - within the range 0..0xFFFF).

Backends

AppCUI supports various backends (but each one comes with advantages and drawbacks). A backend is the terminal that takes the information (characters) from the virtual screen of AppCUI and displays them.

Each backend supported by AppCUI has the following properties:

• Output rendering - each character from the AppCUI surface is display on the screen
• Input reading - the backend is capable of identifying keyboard and mouse events and convert them to internal AppCUI events
• Clipboard support - the backend interacts with the OS and provides functionality for Copy / Cut / Paste based on OS-es API

The following backends are supported:

1. Windows Console
2. Windows VT (Virtual Terminal)
3. NCurses
4. Termios
5. Web Terminal

Remarks: These types are available via appcui::backend::Type and can be used to initialize an application

#![allow(unused)]
fn main() {
let mut a = App::with_backend(apcui::backend::/*type*/).build()?;
}

where the appcui::backend::Type enum is defined as follows:

#![allow(unused)]
fn main() {
pub enum Type {
    #[cfg(target_os = "windows")]
    WindowsConsole,
    #[cfg(target_os = "windows")]
    WindowsVT,
    #[cfg(target_family = "unix")]
    Termios,
    #[cfg(target_os = "linux")]
    NcursesTerminal,
    #[cfg(target_arch = "wasm32")]
    WebTerminal,
}
}

OS Support

Display

Keyboard

Mouse

System events

Other capabilities

Clipboard

AppCUI provides clipboard support for copying and pasting text. The clipboard functionality is available on the following backends:

Defaults

By default, when using initializing a backend, the folowing will be used:

Windows Console

This backend replies on the following Windows API for various console related tasks:

For clipboard based operations, it relies on the following APIs:

• OpenClipboard
• EmptyClipboard
• CloseClipboard
• SetClipboardData
• GetClipboardData
• IsClipboardFormatAvailable

Remarks: For this type of backend to work, there is no need for a 3rd party crate (everything is done via FFI and direct API calls).

Limitations

Windows uses WTF-16 (that does not encode the full range of unicode characters). While unicode surrogates are supported, depending on the version of windows some characters (usually with a code higher than 0xFFFF) might not be disply accurtely or my move the line they are down into to the left.

Windows VT (Virtual Terminal)

This backend is based on both Windows API and VT100 escape sequences.

For clipboard based operations, it relies on the following APIs:

• OpenClipboard
• EmptyClipboard
• CloseClipboard
• SetClipboardData
• GetClipboardData
• IsClipboardFormatAvailable

Input (mouse / keyboard / console resize) is handled by the following APIs:

The output is done via VT100 escape sequences (please refer to Wikipedia for more information). This backend supports true colors (24 bits per pixel) and wide characters (2 bytes per character) but it depends on the Windows version to support them.

Limitations:

Because of the way VT100 escape sequences work, the backend is much slower than a regular Windows Console backend (that renders the output directly into the console). If speed is a priority, it is recommended to use the Windows Console backend instead.

Keep in mind that the speed limitation can be mitigated by using a 3rd party terminal (that use the GPU to render the output)such as:

• RIO
• Alacritty

Usage

Windows VT is not the default backend on Windows. To use it, you need to specify the WindowsVT backend type when creating the application:

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    let app = App::with_backend(appcui::backend::Type::WindowsVT).build()?;
    // build your application here
    Ok(())
}

Further more, if you also want to use true colors you will need to enable the TRUE_COLORS feature when building the application:

[dependencies]
appcui = { version = "*", features = ["TRUE_COLORS"] }

Ncurses Terminal

Installing ncurses Library

To use the ncurses terminal library in your Rust project, you need to install the ncurses library on your system. Here's how you can install it on different platforms:

Ubuntu/Debian

sudo apt-get install libncurses5-dev libncursesw5-dev

macOS

brew install ncurses

Limitations of ncurses

While ncurses is a powerful terminal library, it does have some limitations to be aware of:

• ncurses is primarily designed for ASCII characters and may not handle wide characters properly.
• Wide characters, such as Unicode characters, may not be displayed correctly or may cause unexpected behavior.
• Some terminal emulators may not fully support all ncurses features, leading to inconsistent behavior across different terminals.

It's important to consider these limitations when using ncurses in your Rust project, especially if you need to work with wide characters or require consistent behavior across different terminals.

AppCUI uses ncursesw for wide character support, in order to render multiple Unicode chars.

Termios

Summary

Termios is a low-level library for terminal manipulation on UNIX systems. It is utilized in AppCUI to handle terminal input and output on macOS.

Implementation Details

When a TermiosTerminal instance is initialized, the terminal is configured to operate in raw mode. This mode allows the application to capture individual key press events directly, bypassing line buffering and other default terminal behaviors. To facilitate advanced input handling, a specific byte sequence is sent to stdout to enable mouse events, allowing AppCUI to handle mouse interactions.

To adapt to dynamic terminal conditions, a signal handler is set up to monitor window resize events (SIGWINCH). This ensures that the terminal layout is updated appropriately when the terminal window's dimensions change.

At the lowest level, the implementation involves reading one or more bytes directly from stdin. This is performed using a blocking read operation on a separate thread to avoid interfering with the application's main execution flow. These bytes are then interpreted into a SystemEvent, which is dispatched to the runtime manager for further processing.

Limitations

• Screen flickering: Screen updates may cause flickering because the screen content is not flushed all at once. We have not yet found a solution for this issue.
• Key Combination Limitations: Certain key combinations on macOS cannot be uniquely identified due to limitations in the terminal's input byte encoding. For example:
  • Enter, Command + Enter, Option + Enter, and Control + Enter all produce the same byte sequence
  • Control + H and Control + Backspace produce conflicting byte sequences

TODO

The following features are missing from the Termios Terminal implementation:

• Text Styling: Support for CharFlags (bold, italic, underlined characters)
• Key Mapping: Some keys and key combinations are either unmapped or incorrectly mapped
• Cursor Visibility: Hiding the cursor is not supported

Web Terminal

Summary

The Web Terminal allows AppCUI applications to run in a web browser using WebAssembly, WebGL for rendering, and JavaScript for event handling.

Prerequisites

Before you begin, make sure you have:

• Rust Toolchain:

  [!IMPORTANT] Use the nightly toolchain, as this project requires unstable features.

• wasm-bindgen: Add the following dependency in your Cargo.toml:

  wasm-bindgen = { version = "0.2" }
  

• wasm-pack: Install wasm-pack for building your WebAssembly package.
• A Web Server: Use the provided server.py below or any static server to serve your files.

  [!WARNING] If using threads, make sure to serve all your files in browser with these headers:

  Cross-Origin-Opener-Policy: "same-origin"
  Cross-Origin-Embedder-Policy: "require-corp"
  

Setup

1. Configure Rust for WebAssembly

Create or update your .cargo/config.toml to include the following target configuration:

[target.wasm32-unknown-unknown]
rustflags = [
    "-C", "target-feature=+atomics,+bulk-memory,+mutable-globals"
]

[unstable]
build-std = ["panic_abort", "std"]

This configuration enables atomic operations, bulk memory, and mutable globals on the wasm32-unknown-unknown target, and ensures that the build uses the required unstable std features.

2. Create a Library Package

Ensure your Rust project is set up as a library. In your library entry point, add the wasm-bindgen start macro to export your start function:

#![allow(unused)]
fn main() {
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen(start)]
pub fn start() {
    // your code
}
}

Make sure that your library depends on the appcui crate and that you use its features for rendering and input handling.

Building the Package

Use wasm-pack to compile the project for the web target:

wasm-pack build --target web

Ensure that your Cargo project has the target wasm32-unknown-unknown installed. You can do so with:

rustup target add wasm32-unknown-unknown

Example HTML File

Below is an example index.html that sets up the canvases and loads the compiled WebAssembly package.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Web Terminal Test</title>
  <style>
    html, body {
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    #canvas, #textCanvas {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      display: block;
      background: transparent;
    }
    #textCanvas {
      pointer-events: none;
    }
    .config {
      display: none;
    }
  </style>
</head>
<body>
  <canvas id="canvas"></canvas>
  <canvas id="textCanvas"></canvas>

  <div class="config">
    <span id="terminal-cols">211</span>
    <span id="terminal-rows">56</span>
    <span id="terminal-font">Consolas Mono, monospace</span>
    <span id="terminal-font-size">20</span>
  </div>

  <script type="module">
    console.log("SharedArrayBuffer available:", typeof SharedArrayBuffer !== "undefined");
    import init, * as wasm from "./pkg/your_application.js"; // Replace 'your_application' with your package name

    init({
      module: new URL("./pkg/your_application.wasm", import.meta.url), // Replace 'your_application'
      memory: new WebAssembly.Memory({ initial: 200, maximum: 16384, shared: true })
    }).then(async () => {
      console.log("WASM module initialized");
      // Example: Initialize a thread pool if your application uses threads
      // await wasm.initThreadPool(navigator.hardwareConcurrency); 

      if (wasm.start) { // Ensure your exported start function is called
        wasm.start();
        console.log("WASM start function called");
      }
    });
  </script>
</body>
</html>

This file:

• Creates two canvases: one for WebGL background rendering (canvas) and one for text rendering (textCanvas).
• Includes a hidden configuration section for terminal settings (cols, rows, font, font size). These values are read by the WebTerminal in appcui.
• Imports the WebAssembly package and initializes it. Make sure to replace your_application with the actual name of your wasm package.

Running the Server

A simple Python server for hosting the application:

import http.server
import socketserver
import os

class CustomHandler(http.server.SimpleHTTPRequestHandler):
    def send_head(self):
        path = self.translate_path(self.path)
        if os.path.isfile(path):
            f = open(path, 'rb')
            fs = os.fstat(f.fileno())
            self.send_response(200)
            if path.endswith('.js'):
                mime_type = "application/javascript"
            elif path.endswith('.wasm'):
                mime_type = "application/wasm"
            else:
                mime_type = "text/html"
            self.send_header("Content-Type", mime_type)
            self.send_header("Content-Length", str(fs.st_size))
            self.send_header("Cross-Origin-Opener-Policy", "same-origin")
            self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
            self.end_headers()
            return f
        return super().send_head()

    def do_GET(self):
        f = self.send_head()
        if f:
            try:
                self.wfile.write(f.read())
            finally:
                f.close()

PORT = 4000
with socketserver.TCPServer(("", PORT), CustomHandler) as httpd:
    print(f"Serving on port {PORT}")
    httpd.serve_forever()

To run the example Python server (assuming you are in the directory containing server.py and your index.html and pkg folder):

python server.py

Then navigate to http://localhost:4000/index.html (or the appropriate address and port for your server) in your browser.

Implementation Details

The WebTerminal uses two HTML canvas elements:

• One canvas (canvas) is used for WebGL rendering of cell backgrounds. This allows for efficient rendering of colored backgrounds.
• A second canvas (textCanvas) is overlaid on top for rendering text characters.
• Event handling (keyboard, mouse) is done via JavaScript event listeners attached to the document, which then forward events to the Rust/WASM module.
• Configuration for terminal dimensions, font, etc., is typically read from hidden HTML elements on the page.

Limitations

• Performance can vary depending on the browser and the complexity of the UI.
• Threading support relies on SharedArrayBuffer, which requires specific HTTP headers (Cross-Origin-Opener-Policy: "same-origin" and Cross-Origin-Embedder-Policy: "require-corp") to be set by the web server.
• Clipboard integration uses the browser's asynchronous clipboard API.

Controls

All controls from AppCUI follow a tree-like organization (a control has a parent control and may have multiple children controls).

Remarks

• There is only one Desktop control. AppCUI provides a default one, but costom desktop can be created as well
• A Desktop control can have one or multiple Windows.
• All events emitted by any control are process at window level
• A control may contain other children controls

Every control has a set of common characteristics:

1. Layout (how it is position relative to its parent). The only exception in this case is the Desktop control that always takes the entire terminal space. More details on Layout section.
2. Visibility (a control can be visible or not). The only exception is the Desktop control that will always be visible. A hidden control does not receive any input events and it is not drawn.
3. Enabled (a control can be enabled or not). The only exception are the Desktop and Window controls that are always enabled. If a control is not enabled, it will not receive any input events (key pressed or mouse events) but it will still be drawn.
4. HotKey (a combination of keys usually at the following form: Alt+<Letter|Number> that will automatically change the focus to the current control and execute a default action for it - for example for a checkbox, pressing that combination will check or uncheck the checkbox)

Besides this, a set of commonly available methods are available for all controls. These methods allow changing / accessing some attributes like visibility, loyout, hotkeys, etc. More deails can be found on Common methods for all Controls section.

Layout

Each control in AppCUI is created based on a layout rule that can be described as an ascii string that respects the following format:

"key:value , key:value , ... key:value"

Where key can be one of the following:

Remarks

• Key aliases can be use to provide a shorter format for a layout. In other words, the following two formats are identical: x:10,y:10,width:30,height:30 and x:10,y:10,w:30,h:30
• A numerical value is represented by an integer (positive and negative) number between -30000 and 30000. Example: x:100 --> X will be 100. Using a value outside accepted interval ([-30000..30000]) will reject the layout.
• A percentage value is represented by a floating value (positive and negative) succeded by the character % between -300% and 300%. Example: x:12.75% --> X will be converted to a numerical value that is equal to the width of its parent multiplied by 0.1275. Using a value outside accepted interval ([-300%..300%]) will reject the layout. Percentage values can be use to ensure that if a parent size is changed, its children change their size with it.
• All layout keys are case insensitive (meaning that 'left=10' and 'LEFT=10' have the same meaning)

Dock values can be one of the following:

Remarks:

• Dock value aliases can be use to provide a shorter format for a layout. In other words: dock:topleft is the same with dock:tl or dock:lt or d:tl

Align values have the same name as the docking ones, but they refer to the direction of width and height from a specific point (denoted by "X" and "Y" keys). Align parameter is used to compute top-left and bottom-right corner of a control that is described using a (X,Y) coordonate. The following table ilustrate how this values are computed:

Remarks:

• Align value aliases can be use to provide a shorter format for a layout. In other words: align:center is the same with align:c or a:c

Absolute position

In this mode parameters x and y must be used to specify a point from where the control will be constructed. When using this mode, parameters dock, left, right, top, bottom can not be used. If width or height are not specified , they will be defaulted to 1 character (unless there is a minimum width or minumum height specified for that controls - in which case that limit will be applied). If align is not specified, it will be defaulted to topleft

If x, y, width or height are provided using percentages, the control will automatically adjust its size if its parent size changes.

Layout	Result
x:8,y:5,w:33%,h:6 or x:8,y:5,w:33%,h:6,a:tl	If no alignament is provided, top-left will be considered as a default.
x:30,y:20,w:33%,h:6,a:br
x:50%,y:50%,w:25,h:8,a:c

Docking

To dock a control inside its parent use d or dock key. When docking a control, the following keys can not be used: align, x, y, left, right, top, bottom. Width and height should be used to specify the size of control. If not specified, they are defaulted to 100%.

Layout	Outcome
d:c,w:30,h:50%
d:bl,w:50%	As height is not specified, it will be defaulted to 100%
d:c or d:tl or d:br or any dock without width and height parameter	As both width and height parameters are missing, they will be defaulted to 100%. This means that current control will ocupy its entire parent surface. This is the easyest way to make a control fill all of its parent surface.

Anchors

Anchors (left, right, top and bottom) represent the distance between the object and its parent margins. When one of the anchors is present, the dock key can not be used. Depending on the combination of anchors used, other keys may be unusable.

Corner anchors

Corner anchors are cases when the following combinations of anchors are used toghether (left and top), (left and bottom), (right and top) and (right and bottom). When this combinations are used, x and y keys can not be used. Using them will reject the layout. If width or height are not specified , they will be defaulted to 1 character (unless there is a minimum width or minumum height specified for that controls - in which case that limit will be applied).

The combination of anchors also decides how (top,left) and (right,bottom) corners of a control are computed, as follows:

where:

• parentWidth is the width of the parent control
• parentHeight the height of the parent control

Examples

Layout	Result
t:10,r:20,w:50,h:20
b:10,r:20,w:33%,h:10
b:10%,l:50%,w:25%,h:10

Using Left-Right anchors

When Left and right anchors are used together, there are several restrictions. First of all, width and x parameters can not be specified. Width is deduced as the difference between parents width and the sum of left and right anchors. Left anchor will also be considered as the "x" coordonate. However, height parameter should be specified (if not specified it will be defaulted to 1 character (unless a minimum height is specified for that controls - in which case that limit will be applied). align paramter can also be specified , but only with the following values: top, center or bottom. If not specified it will be defaulted to center.

Examples

Layout	Result
l:10,r:20,h:20,y:80%,a:b
l:10,r:20,h:100%,y:50%,a:c
l:10,r:20,h:50%,y:0,a:t

Using Top-Bottom anchors

When top and bottom anchors are used together, there are several restrictions. First of all, height and y parameters can not be specified. Height is deduced as the difference between parents height and the sum of top and bottom anchors. Top anchor will also be considered as the "y" coordonate. However, width parameter should be specified (if not specified it will be defaulted to 1 character (unless a minimum width is specified for that controls - in which case that limit will be applied). align paramter can also be specified , but only with the following values: left, center or right. If not specified it will be defaulted to center.

Examples

Layout	Result
t:10,b:20,w:90,x:80%,a:r
t:10,b:20,w:100%,x:50%,a:c
t:10,b:20,w:50%,x:0,a:l

3-margin anchors

When using 3 of the 4 anchors, the following keys can not be used: x, y, align and dock. Using them will reject the layout. The following table reflects these dependencies:

Remarks

• if height or width are not present and can not be computed as a difference between two margins, they are defaulted to value 1. If limits are present (min Width or min Height) those limits are applied. This is usually usefull for controls that have a fixed width or height (e.g. a button, a combobox).

The position of the control is also computed based on the combination of the 3 anchors selectd, as shown in the next table:

where:

• parentWidth is the width of the parent control
• parentHeight the height of the parent control

Examples

Layout	Result
l:10,t:8,r:20,h:33%
l:20,b:5,r:10,h:33%
l:10,t:8,b:15,w:80%
r:30,t:8,b:20%,w:50%%

4-margin anchors

When all of the 4 anchors, the rest of the keys ( x, y, width, height, align and dock) can not be used. Using them will reject the layout.

Example

Layout	Result
l:20,t:7,r:10,b:10

Instantiate a control using macros

All controls can be build via their constructors, but also via some specialized macros that are meant to ease setting up a controller. The general format is as follows: controller!("<parameter_list>"), where the controller! is a specialized macro (for example button!) and the parameter_list is a json-like/python-like format, form out of:

• positional parameters - for example in this case: "10,20,30" has three positional parameters 10, 20 and 30
• named parameters - are parameters described using a name and a value. The usual format is name:value but name=value is also supported.

All parameters are separated one from onether using , or ;. The overall format of a parameter list is:

PostionalParam-1, ... PostionalParam-n, NamedParam-1,  ... NamedParam-m

Both positional parameters and named parameters are optionally. Their order however it is not. Positional parameters (if used) should always be placed before named parameters.

Values

The values used as parameters can be:

• regula word (ex: align:center)
• numerical values (ex: x=10or y=-2)
• percentages (ex: width:10% or height=25%)
• strings - a string can be separated between douple quotes or single quotes and can contain new lines (ex: "..." or '...'). If both a single quote and a double quote has to be used in a string, three consecuitev double or single quotes can be used (ex: """...""" or '''...''')
• list of values - obtained using [ and ] characters. The general format is [value-1, value-2, ... value-n] - ex: [10,20,30] is a list with three values 10,20 and 30.
• another parameter list - obtained using [ and ] characters. The general format is {parameter list} - for example the following syntax point={x:10,y:20} translates into parameter point being defined as a set of two parameters x with value 10 and y with value 20.
• flags - flags are a meta interpretation for the previously described parameters. It can be a regular word / string or a list of values. If using a word you can separate flags using one of the following characters: | and +. Aditionally when using a strings, spaces, , and ; cand also be used as a separator. When using a list of values, each one of the values is a separate flag. For example the following declarations are equivalent:
  • flags=[flag1,flag2]
  • flags=flag1+flag2
  • flags=flag1|flag2
  • flags="flags1,flags2"
  • flags="flags1;flags2"
  • flags="flags1 flags2"

Common parameters

All controls have a set of common parameters that are required for layout or to change some of their states (such as visibility or if a control is enabled - can receive input).

Common methods for all Controls

All controls (including Window and Desktop) have a set of common methods obtaing via Deref trait over a common base object.

Status related methods

Layout related methods

Hotkey related methods

Update methods

Menu related methods

Theme related methods

Event loop

AppCUI is an event driven framework, meaning that each control can emit events to reflect various acions or changes that occur. For example, whenever you push a button, an event will be raise. All events are process at Window level by implementing various traits. To build a Window that supports event handling, you must use a special procedural macro call Window, defined in the the following way:

#[Window(events=..., )]
struct MyWindow {
    // specific fields
}

where the attribute events has the following form:

• events=EventTrait-1 + EventTrait-2 + EventTrait-3 + ... EventTrait-n

and an event trait can be one of the following:

• ButtonEvents
• CheckBoxEvents
• RadioBoxEvents
• WindowEvents
• MenuEvents
• CommandBarEvents
• ToolBarEvents
• ColorPickerEvents
• ThreeStateBoxEvents
• PasswordEvents
• KeySelectorEvents
• TextFieldEvents

These events can be implemented to receive notification on various actions that children controls are performing.

When creating a window that supports event loop in this manner, you will need to instantiate it. A common approach is the following:

#[Window(events=..., )]
struct MyWindow {
    // specific fields
}
impl MyWindow {
    fn new(/* extra parameters */) -> Self {
        let mut obj = MyWindow {
            base: Window::new(title, layout, flags);
            // initialization other fileds from MyWindow i
        }
        // other initialization (such as creating children)
        return obj;
    }
}

The initializaton base: Window::new(title, layout, flags); is mandatory. As for the title, layout and flags you can provide them as parameters in the new method or you can infer them / or hardcode them in a different way. More on how a Window can be created on Window page.

Once you create an event loop you can add it to your application using add_window(...) method.

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    app.add_window(MyWindow::new(/* parameters */));
    app.run();
    Ok(())
}

A simple example

Let's start with a simple example that creates such a window that has a fixed sized of 40x20 characters and two internal i32 values.

use appcui::prelude::*;

#[Window()]
struct MyWindow {
    value1: i32,
    value2: i32
}
impl MyWindow {
    fn new(title: &str) -> Self {
        MyWindow {
            base: Window::new(title, Layout::new("d:c,w:40,h:20"), window::Flags::None);
            value1: 0,
            value2: 1
        }
    }
}
fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    app.add_window(MyWindow::new("Some title"));
    app.run();
    Ok(())
}

Intercepting events from a child control

Usually, a window that processes events mentains a handle to various controls and enable event processing in the #[Window(...)] declaration.

use appcui::prelude::*;

#[Window(events = /*Events specific to a control */)]
struct MyWindow {
    value1: i32,
    control: Handle</*control type*/>
}
impl MyWindow {
    fn new(/* parameters */) -> Self {
        let mut mywin = MyWindow {
            base: Window::new(/*...*/);
            control: Handle::None
        }
        // now we create the control
        mywin.control =  mywin.add(/* Code that creates a control */);

        return mywin;
    }
}
impl /*Control event*/ for MyWindow {
    // add logic for event
}
fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    app.add_window(MyWindow::new(/* parameters */));
    app.run();
    Ok(())
}

For every control described in Stock Controls an example on how that control can be used with the event loop and the type of events it emits will be presented.

Window

A window is the core component of an application and it is the object where all events from children controls are being processed.

To create a Window use:

• Window::new method (with 3 parameters: a title, a layout and initialization flags)
• Window::with_type method (with 4 parameters: a title, a layout , initialization flags and a type)
• macro window!.

let w = Window::new("Title", Layout::new("x:10,y:5,w:15,h:9"),window::Flags::None);
let w2 = window!("Title,d:c,w:10,h:10");
let w3 = window!("title='Some Title',d:c,w:30,h:10,flags=[Sizeable])");
let w4 = window!("title='WithTag',d:c,w:30,h:10,tag:MyTag)");
let w5 = window!("Title,d:c,w:10,h:10,key:Alt+F10");
let w6 = window!("Title,d:c,w:10,h:10,key:auto");

Keep in mind that window will NOT handle any events from its children.

A window supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

To create a window that will handle events from its children, use #[Window(...)] method:

#[Window(events=..., )]
struct MyWindow {
    // specific fields
}

A window supports the following initialization flags:

• window::Flags::None - regular window (with a close button)
• window::Flags::Sizeable or Sizeable (for window! macro) - a window that has the resize grip and the maximize button
• window::Flags::NoCloseButton or NoCloseButton (for window! macro) - a window without a close button
• window::Flags::FixedPosition or FixedPosition (for window! macro) - a window that can not be moved

and the following types:

• window::Type::Normal or Normal (for window! macro) - a regular window
• window::Type::Error or Error (for window! macro) - a window with a red background to indicate an error message
• window::Type::Notification or Notification (for window! macro) - a window with a different background designed for notification messages
• window::Type::Warning or Warning (for window! macro) - a window with a different background designed for Warning messages

Methods

Besides the Common methods for all Controls a button also has the following aditional methods:

Key association

In terms of key association, a Window has two modes:

• Normal mode (for whem a window is has focus)
• Resize/Move mode (in this mode you can use arrows and various combinations to move the window)

For normal mode

OBS: Keep in mind that if any of these keys (in particular Left, Right, Up and Down) are capture by one of the children of a window, they will not pe process by the window.

For resize/move mode

Events

Window related events can be intercepted via WindowEvents trait. You will need to add WindowEvents in the list of events like in the following example:

#![allow(unused)]
fn main() {
#[Window(events=WindowEvents)]
struct MyWindow { ... }
impl WindowEvents for MyWindow { ... }
}

WindowEvents is defined in the following way:

#![allow(unused)]
fn main() {
pub trait WindowEvents {
    fn on_close(&mut self) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
    fn on_layout_changed(&mut self, old_layout: Rect, new_layout: Rect) {}
    fn on_activate(&mut self) {}
    fn on_deactivate(&mut self) {}
    fn on_accept(&mut self) {}
    fn on_cancel(&mut self) -> ActionRequest {
        ActionRequest::Allow
    }
}
}

These methods are called under the following scenarious:

Window Tags

For every window, a tag can be set for a window (a tag is a string associated with a Window that reflects its purpose). To set a tag use .set_tag("<name") method. For example, the following code:

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut win = window!("Title,d:c,w:40,h:9");
    win.set_tag("TAG");
    app.add_window(win);
    app.run();
    Ok(())
}

should generate a window that looks like the following:

Window Hot Key

You can also associate a hot key to a window. A hot key allows you to quickly switch between windows. In the next example, we set up Alt+7 as a hot key for a windows.

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut win = window!("Title,d:c,w:40,h:9");
    win.set_hotkey(key!("Alt+7"));
    app.add_window(win);
    app.run();
    Ok(())
}

should generate a window that looks like the following:

Toolbar

A toolbar is a generic concept of an area over the margins of a window (top or bottom margins) where several controls (or toolbar items) reside. A toolbar items are simplier controls that convey their events directly to the window via a spcial trait: ToolBarEvents.

All toolbar items are organized in groups. A group is similar to a flow (all toolbar items are aligned one after another, depending on the direction of the flow). It is important to notice that a toolbar item does not have a layout of itself (its position is decided by the group). The following direction are supported by a toolbar group (via enum toolbar::GroupPosition):

pub enum GroupPosition {
    TopLeft,
    BottomLeft,
    TopRight,
    BottomRight,
}

Constructing a toolbar item

To add a toolbar item into a window, you need to perform the following steps:

1. create a group
2. create a toolbar item
3. add the previously created toolbar item to the group created on step 1.

Typically, a toolbar initialization mechanims is done when creating a window, in a similar manner as with the next snippet:

#[Window(...)]
struct MyWin {
    // data members
}
impl MyWin {
    fn new() -> Self {
        let mut me = Self {
            base: window!("..."),
        };
        let a_group = me.toolbar().create_group(toolbar::GroupPosition::<Value>);
        let item_handle = me.toolbar().add(a_group, toolbar::<Type>::new("..."));
        // other initializations
        me
    }
}

To create a toolbar item, there are two options:

• use toolbar::<Item>::new(...) method
• use toolbaritem! macro

Curenly AppCUI supports the following toolbar item types:

• Label
• CheckBox
• SingleChoice
• Button

Common methods

All toolbar items have a set of common methods that can be used to modify their behavior:

Button toolbar item

A toolbar button is a item that can be positioned on the top or bottom part of a windows (like in the following image).

To create a button within a toolbar use the toolbar::Button::new(...) method:

#![allow(unused)]
fn main() {
let toolbar_button = toolbar::Button::new("content");
}

or the toolbaritem! macro:

#![allow(unused)]
fn main() {
let toolbar_button_1 = toolbaritem!("content,type=button");
let toolbal_button_2 = toolbaritem!("content='Start',type:button");
let toolbal_button_3 = toolbaritem!("content='&Stop',type:button,tooltip:'a tooltip'");
let toolbal_button_4 = toolbaritem!("content='hidden button',type:button,visible:false");
}

Using the character & as part of the button caption will associate the next character (if it is a letter or number) as a hot-key for the button. For example, the following caption St&art will set Alt+A as a hot-key for the button.

The following parameters are supported for a toolbar button:

Besides the default methods that every toolbar item has (as described here), the following methods are available for a toolbar label:

Events

To intercept button clicks, implement ToolBarEvents for the current window, as presented in the following example:

#![allow(unused)]
fn main() {
#[Window(events=ToolBarEvents)]
struct MyWin { /* data members */ }

impl ToolBarEvents for MyWin {
    fn on_button_clicked(&mut self, handle: Handle<toolbar::Button>) -> EventProcessStatus {
        // process click events from a toolbar button
    }
}
}

Example

The following example creates two buttons on the bottom right part of a window toolbar that can be used to increase the value of a number.

#[Window(events = ToolBarEvents)]
struct MyWin {
    increase_button: Handle<toolbar::Button>,
    decrease_button: Handle<toolbar::Button>,
    text: Handle<Label>,
    number: u32,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:6"),
            increase_button: Handle::None,
            decrease_button: Handle::None,
            text: Handle::None,
            number: 10,
        };
        // create a group
        let g = win.toolbar().create_group(toolbar::GroupPosition::BottomRight);
        // add buttons
        win.increase_button = win.toolbar().add(g, toolbar::Button::new("+"));
        win.decrease_button = win.toolbar().add(g, toolbar::Button::new("-"));
        // add a label
        win.text = win.add(label!("10,d:c,w:2,h:1"));
        win
    }
}
impl ToolBarEvents for MyWin {
    fn on_button_clicked(&mut self, handle: Handle<toolbar::Button>) -> EventProcessStatus {
        match () {
            _ if handle == self.increase_button => self.number += 1,
            _ if handle == self.decrease_button => self.number -= 1,
            _ => {}
        }
        let h = self.text;
        let n = self.number;
        if let Some(label) = self.control_mut(h) {            
            label.set_caption(format!("{}", n).as_str());
        }
        EventProcessStatus::Processed
    }
}

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

CheckBox toolbar item

A toolbar checkbox is a item that can be positioned on the top or bottom part of a windows (like in the following image) that can have two states (checked or un-checked).

To create a checkbox within a toolbar use the toolbar::CheckBox::new(...) method:

#![allow(unused)]
fn main() {
let toolbar_checkbox = toolbar::CheckBox::new("content", true);
}

or the toolbaritem! macro:

#![allow(unused)]
fn main() {
let toolbar_checkbox_1 = toolbaritem!("content,type=checkbox");
let toolbal_checkbox_2 = toolbaritem!("content='Start',type:checkbox,checked: true");
let toolbal_checkbox_3 = toolbaritem!("content='&Stop',type:checkbox,tooltip:'a tooltip'");
let toolbal_checkbox_4 = toolbaritem!("content='hidden checkbox',type:checkbox,visible:false");
}

Using the character & as part of the button caption will associate the next character (if it is a letter or number) as a hot-key for the checkbox. For example, the following caption &Option one will set Alt+O as a hot-key for the checkbox.

The following parameters are supported for a toolbar checkbox:

Besides the default methods that every toolbar item has (as described here), the following methods are available for a toolbar label:

Events

To intercept a change in a checkbox checked state, you need to implement ToolBarEvents for the current window, as presented in the following example:

#![allow(unused)]
fn main() {
#[Window(events=ToolBarEvents)]
struct MyWin { /* data members */ }

impl ToolBarEvens for MyWin {
    fn on_checkbox_clicked(&mut self, handle: Handle<toolbar::CheckBox>, checked: bool) -> EventProcessStatus {
        // do an action based on the new state of the checkbox
        // parameter `checked` is true if the toolbar checkbox is checked or false otherwise 
    }
}
}

Example

The following example creates a window with two checkboxes toolbar items and a label. Clicking on each one of the checkboxes will show a message on the label that states the check state of that checkbox.

#[Window(events = ToolBarEvents)]
struct MyWin {
    cb1: Handle<toolbar::CheckBox>,
    cb2: Handle<toolbar::CheckBox>,
    text: Handle<Label>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:6"),
            cb1: Handle::None,
            cb2: Handle::None,
            text: Handle::None,
        };
        // create a group
        let g = win.toolbar().create_group(toolbar::GroupPosition::BottomRight);
        // add checkboxes
        win.cb1 = win.toolbar().add(g, toolbar::CheckBox::new("Opt-1",false));
        win.cb2 = win.toolbar().add(g, toolbar::CheckBox::new("Opt-2",false));
        // add a label
        win.text = win.add(label!("'',d:c,w:20,h:1"));
        win
    }
}
impl ToolBarEvents for MyWin {
    fn on_checkbox_clicked(&mut self, handle: Handle<toolbar::CheckBox>, checked: bool) -> EventProcessStatus {
        let txt = match () {
            _ if handle == self.cb1 => format!("Opt-1 is {}",checked),
            _ if handle == self.cb2 => format!("Opt-2 is {}",checked),
            _ => String::new(),
        };
        let h = self.text;
        if let Some(label) = self.control_mut(h) {
            label.set_caption(&txt);
        }
        EventProcessStatus::Processed
    }
}

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

Label toolbar item

A toolbar label is a text that can be written on the top or bottom part of a windows (like in the following image).

To create a label toolbar use the toolbar::Label::new(...) method:

#![allow(unused)]
fn main() {
let toolbar_label = toolbar::Label::new("content");
}

or the toolbaritem! macro:

#![allow(unused)]
fn main() {
let toolbar_label_1 = toolbaritem!("content,type=label");
let toolbal_label_2 = toolbaritem!("content='label text',type:label");
let toolbal_label_3 = toolbaritem!("content='label text',type:label,tooltip:'a tooltip'");
let toolbal_label_4 = toolbaritem!("content='hidden label',type:label,visible:false");
}

The following parameters are supported for a toolbar label:

Besides the default methods that every toolbar item has (as described here), the following methods are available for a toolbar label:

Example

The following example shows 3 lables that show a number written in base 10, 16 and 2.

• the first two labels (for base 10 and base 16 are part of one group located on the bottom left part of the window);
• the last label is part of a separate group located on the top-right side of the window.
• at the left of the window, there is a button that if clicked increases the number and updates the values in each label;
• at the right of the window, 3 checkboxes can change the visibility state for the labels

#[Window(events = ButtonEvents+CheckBoxEvents)]
struct MyWin {
    increase_button: Handle<Button>,
    dec: Handle<toolbar::Label>,
    hex: Handle<toolbar::Label>,
    bin: Handle<toolbar::Label>,
    show_dec: Handle<CheckBox>,
    show_hex: Handle<CheckBox>,
    show_bin: Handle<CheckBox>,
    number: u32,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:6"),
            increase_button: Handle::None,
            dec: Handle::None,
            hex: Handle::None,
            bin: Handle::None,
            show_dec: Handle::None,
            show_hex: Handle::None,
            show_bin: Handle::None,
            number: 24,
        };
        // add the increase button
        win.increase_button = win.add(button!("Increase,w:15,d:l"));
        // add checkboxes
        win.show_dec = win.add(checkbox!("'Show decimal',x:20,y:1,w:16,checked:true"));
        win.show_hex = win.add(checkbox!("'Show hex',x:20,y:2,w:16,checked:true"));
        win.show_bin = win.add(checkbox!("'Show binary',x:20,y:3,w:16,checked:true"));
        // add toolbar labels
        let first_group = win.toolbar().create_group(toolbar::GroupPosition::BottomLeft);
        let second_group = win.toolbar().create_group(toolbar::GroupPosition::TopRight);
        win.dec = win.toolbar().add(first_group, toolbar::Label::new(""));
        win.hex = win.toolbar().add(first_group, toolbar::Label::new(""));
        win.bin = win.toolbar().add(second_group, toolbar::Label::new(""));
        win.update_toolbar_labels();
        win
    }
    fn update_toolbar_label(&mut self, handle: Handle<toolbar::Label>, text: String) {
        if let Some(label) = self.toolbar().get_mut(handle) {
            label.set_content(text.as_str());
        }
    }
    fn update_visibility_status_for_label(&mut self, handle: Handle<toolbar::Label>, visible: bool) {
        if let Some(label) = self.toolbar().get_mut(handle) {
            label.set_visible(visible);
        }        
    }
    fn update_toolbar_labels(&mut self) {
        self.update_toolbar_label(self.dec, format!("Dec:{}", self.number));
        self.update_toolbar_label(self.hex, format!("Hex:{:X}", self.number));
        self.update_toolbar_label(self.bin, format!("Bin:{:b}", self.number));
    }
}

impl ButtonEvents for MyWin {
    fn on_pressed(&mut self, _handle: Handle<Button>) -> EventProcessStatus {
        self.number += 1;
        self.update_toolbar_labels();
        return EventProcessStatus::Processed;
    }
}
impl CheckBoxEvents for MyWin {
    fn on_status_changed(&mut self, handle: Handle<CheckBox>, checked: bool) -> EventProcessStatus {
        match () {
            _ if handle == self.show_bin => self.update_visibility_status_for_label(self.bin, checked),
            _ if handle == self.show_hex => self.update_visibility_status_for_label(self.hex, checked),
            _ if handle == self.show_dec => self.update_visibility_status_for_label(self.dec, checked),
            _ => {}
        }
        EventProcessStatus::Processed
    }
}

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

Upon execution you should see something that looks like the following image:

SingleChoice toolbar item

A toolbar singlechoice item is a item that can be positioned on the top or bottom part of a windows (like in the following image) that can have two states (selected or un-selected).

Within a group, only one singlechoice item can be selected.

To create a checkbox within a toolbar use the toolbar::SingleChoice::new(...) method:

#![allow(unused)]
fn main() {
let toolbar_singlechoice = toolbar::SingleChoice::new("SingleChoice");
}

or the toolbaritem! macro:

#![allow(unused)]
fn main() {
let toolbar_sc_1 = toolbaritem!("content,type=singlechoice");
let toolbal_sc_2 = toolbaritem!("content='Choice One',type:singlechoice");
let toolbal_sc_3 = toolbaritem!("content='&Second choice',type:singlechoice,tooltip:'a tooltip'");
let toolbal_sc_4 = toolbaritem!("content='hidden choice',type:singlechoice,visible:false");
}

Using the character & as part of the button caption will associate the next character (if it is a letter or number) as a hot-key for the singlechoice item. For example, the following caption First &choice will set Alt+C as a hot-key for the singlechoice item.

The following parameters are supported for a toolbar singlechoice:

Besides the default methods that every toolbar item has (as described here), the following methods are available for a toolbar label:

OBS: Keep in mind that using select() method only works if the single choice has already been added to a toolbar. Using this methid without adding the item to a toolbar will result in a panic.

Events

To intercept if the current choice has change, you need to implement ToolBarEvents for the current window, as presented in the following example:

#![allow(unused)]
fn main() {
#[Window(events=ToolBarEvents)]
struct MyWin { /* data members */ }

impl ToolBarEvens for MyWin {
    fn on_choice_selected(&mut self, _handle: Handle<toolbar::SingleChoice>) -> EventProcessStatus {
        // do an action based on the new selection
    }
}
}

Example

The following example creates a window with two single choice toolbar items and a label. Clicking on each one of the singlechoice items will show a message on the label that states the selected singlechoice.

#[Window(events = ToolBarEvents)]
struct MyWin {
    opt1: Handle<toolbar::SingleChoice>,
    opt2: Handle<toolbar::SingleChoice>,
    text: Handle<Label>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:6"),
            opt1: Handle::None,
            opt2: Handle::None,
            text: Handle::None,
        };
        // create a group
        let g = win.toolbar().create_group(toolbar::GroupPosition::BottomLeft);
        // add buttons
        win.opt1 = win.toolbar().add(g, toolbar::SingleChoice::new("First Choice"));
        win.opt2 = win.toolbar().add(g, toolbar::SingleChoice::new("Second Choice"));
        // add a label
        win.text = win.add(label!("'',d:c,w:22,h:1"));
        win
    }
}
impl ToolBarEvents for MyWin {
    fn on_choice_selected(&mut self, handle: Handle<toolbar::SingleChoice>) -> EventProcessStatus {
        let txt = match () {
            _ if handle == self.opt1 => "First choice selected",
            _ if handle == self.opt2 => "Second choice selected",
            _ => "",
        };
        let h = self.text;
        if let Some(label) = self.control_mut(h) {
            label.set_caption(txt);
        }
        EventProcessStatus::Processed
    }
}

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

Modal Window

A modal window is a window that captures the entire focus for the duration of its existance. In other word, when a modal window is started, it will be on top of everything else and the entire input (mouse and keyboard will be treated by it).

When a modal window is opened the rest of the windows or other modal windows will be disabled:

A modal window is in fact just like a regular window (you can add other controls, you can resize and move it) and you can intercept events just like in a regular window case. However, since a modal window can not lose the focus, it has another property (response) that implies that it will provide a response once its execution ends. The response can be any kind of type (including a void type).

To create a modal window that will handle events from its children, use #[ModalWindow(...)] method:

#[ModalWindow(events=..., response=...)]
struct MyModalWindow {
    // specific fields
}

Besides the normal methods that a regular Window has, the following extra methods are available:

Besides the keys that a regular (non-modal) window supports, the following keys have a different purpose:

To disable this behavior, you can add WindowEvents to the list of events and then return ActionRequest::Deny when implementing on_cancel.

#![allow(unused)]
fn main() {
#[ModalWindow(events=WindowEvents, response=...)]
struct MyModalWindow {
    // specific fields
}
impl WindowEvents for MyWindow {
    fn on_cancel(&mut self) -> ActionRequest {
        ActionRequest::Deny
    }
}

}

Execution flow

Normaly, a modal window looks like the following template:

#![allow(unused)]
fn main() {
// ResponseType is a type of data that you want to return
// it could be anything like: u32, String, something user-defined
#[ModalWindow(events=..., response=ResponseType)]
struct MyWindow {
    // specific fields
}
impl MyWindow {
    fn new(...) -> MyWindow { /* constructor */ }
    // other methods
}
// SomeEvent in this context could be any event supported by a Window
// such as: ButtonEvents, ToolBarEvents, ...
impl SomeEvent for MyWindow {
    fn event_methods(&mut self...) {
        // some operations / checks
        self.exit_with(ResponseType::new(...)); // ResponseType::new(...) something that creates a new object of type ResponseType
    }
}
}

Once all of this is in place, you can start the modal window in the following way:

#![allow(unused)]
fn main() {
let r: ResponseType = MyWindow::new(...).show();
}

Example

The following example creates a window with a button that starts a modal window that doubles a value received from the first window.

#[ModalWindow(events=ButtonEvents,response=i32)]
struct MyModalWin {
    value: i32,
}
impl MyModalWin {
    fn new(value: i32) -> Self {
        let mut w = MyModalWin {
            base: ModalWindow::new("Calc", Layout::new("d:c,w:40,h:12"), window::Flags::None),
            value: value * 2,
        };
        w.add(Label::new(format!("{} x 2 = {}", value, value * 2).as_str(), Layout::new("d:c,w:16,h:1")));
        w.add(button!("Close,d:b,w:15"));
        w
    }
}
impl ButtonEvents for MyModalWin {
    fn on_pressed(&mut self, _handle: Handle<Button>) -> EventProcessStatus {
        self.exit_with(self.value);
        EventProcessStatus::Processed
    }
}

#[Window(events = ButtonEvents)]
struct MyWin {
    text: Handle<Label>,
    value: i32,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:16"),
            text: Handle::None,
            value: 1,
        };
        win.text = win.add(label!("'Value=10',d:c,w:24,h:1"));
        win.add(button!("Double,d:b,w:15"));
        win
    }
}
impl ButtonEvents for MyWin {
    fn on_pressed(&mut self, _handle: Handle<Button>) -> EventProcessStatus {
        // first run the modal window
        if let Some(response) = MyModalWin::new(self.value).show() {
            // set the new value
            self.value = response;
            let h = self.text;
            if let Some(label) = self.control_mut(h) {
                label.set_caption(format!("Value={}", response).as_str());
            }
        }
        EventProcessStatus::Processed
    }
}

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

Single Window Apps

A single window app is an AppCUI application where you only have one window that ocupies the entire desktop. Usually, when you create a AppCUI app, you can add multiple windows to a desktop object. In this mode you can only add one window, and terminating that window will close the app.

To do this you need to use the .single_window() method from the App builder as follows:

let mut app = App::new().single_window().build()?;
// add one and only one window
app.add_window(...);
// run the application
app.run()

Remarks

• in a Single Window mode you can not set a custom desktop as there is only one window and it covers the entire visible size of a desktop. Using a .desktop(...) method with a .single_window() method will result in a panic:

  // the following code wil panic
  App::new().single_window().desktop(...).build()?
  

• Since in a Single Window mode there is only one window , you can not use the .add_window(...) method twice. Using it wll result in a panic.

  let mut a = App::new().single_window()..build()?;
  a.add_window(...);
  // the following line will panic as there is alreay a window added
  a.add_window(...); // panic
  a.run();
  

• Since in a Single Window mode the window ocupies the entire visible size of a desktop, you can not resize or move it. As such, window flag attributes like Sizeable are not allowed. If used, the code will panic. The layout (regardless on how you set it up) will be changed to make sure that the window ocupies the entire visible desktop space.

  let mut a = App::new().single_window()..build()?;
  // the following line will panic as Sizeable flag is not allow on windows in Single Window mode
  a.add_window(window!("Test,d:c,flags: Sizeable"));
  a.run();
  

• In a Single Window mode, the event loop will be associated with the single window. As such, not adding a window will result in a panic.

  let mut a = App::new().single_window()..build()?;
  // the following line will panic no window was added
  a.run();
  

Stock controls

AppCUI comes with a set of out-of-the-box controls that can be used:

Control	Class	Macro	Image
Accordion	ui::Accordion	accordion!
Button	ui::Button	button!
Canvas	ui::Canvas	canvas!
CheckBox	ui::CheckBox	checkbox!
ColorPicker	ui::ColorPicker	colorpicker!
ComboBox	ui::ComboBox	combobox!
DatePicker	ui::DatePicker	datepicker!
DropDownList	ui::DropDownList<T>	dropdownlist!
HLine	ui::HLine	hline!
HSplitter	ui::HSplitter	hsplitter!
ImageViewer	ui::ImageViewer	imageviewer!
KeySelector	ui::KeySelector	keyselector!
Label	ui::Label	label!
ListBox	ui::ListBox	listbox!
ListView	ui::ListView<T>	listview!
Markdown	ui::Markdown	markdown!
NumericSelector	ui::NumericSelector<T>	numericselector!
Panel	ui::Panel	panel!
Password	ui::Password	password!
PathFinder	ui::PathFinder	pathfinder!
ProgressBar	ui::ProgressBar	progressbar!
RadioBox	ui::RadioBox	radiobox!
Selector	ui::Selector<T>	selector!
Tab	ui::Tab	tab!
TextArea	ui::TextArea	textarea!
TextField	ui::TextField	textfield!
ThreeStateBox	ui::ThreeStateBox	threestatebox!
ToggleButton	ui::ToggleButton	togglebutton!
TreeView	ui::TreeView<T>	treeview!
VLine	ui::VLine	vline!
VSplitter	ui::VSplitter	vsplitter!

Accordion

An accordion control is a graphical user interface element that consists of a vertically stacked list of panels. Only one panel can be "expanded" to reveal its associated content.

To create an accordion use Accordion::new methods:

let a1 = Accordion::new(Layout::new("d:c,w:15,h:10"),accordion::Flags::None);

or the macro accordion!

let a2 = accordion!("d:c,w:15,h:10,panels:[First,Second,Third]");
let a3 = accordion!("d:c,w:15,h:10,panels:[A,B,C],flags:TransparentBackground");

The caption of each accordion may contain the special character & that indicates that the next character is a hot-key. For example, constructing a accordion panel with the following caption &Start will set up the text of the accordion to Start and will set up character S as the hot key to activate that accordion panel.

A accordion supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A accordion supports the following initialization flags:

• accordion::Flags::TransparentBackground or TransparentBackground (for macro initialization) - this will not draw the background of the accordion

Some examples that uses these paramateres:

let t1 = accordion!("panels:[Tab1,Tab2,Accordion&3],d:c,w:100%,h:100%");
let t2 = accordion!("panels:[A,B,C],flags:TransparentBackground,d:c,w:100%,h:100%");

Events

This control does not emits any events.

Methods

Besides the Common methods for all Controls a accordion also has the following aditional methods:

Key association

The following keys are processed by a Accordion control if it has focus:

Aditionally, Alt+letter or number will automatically select the accordion with that particular hotkey combination.

Example

The following code creates an accordion with 3 panels and adds two buttons on each accordion panel.

use appcui::prelude::*;


fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut w = window!("Test,d:c,w:100%,h:100%");
    let mut t = accordion!("l:1,t:1,r:1,b:3,panels:['Panel &1','Panel &2','Panel &3']");
    t.add(0, button!("T1-1-A,r:1,b:0,w:10,type:flat"));
    t.add(0, button!("T1-1-B,d:c,w:10,type:flat"));      
    t.add(1, button!("T1-2-A,r:1,b:0,w:14,type:flat"));
    t.add(1, button!("T1-2-B,d:c,w:14,type:flat")); 
    t.add(2, button!("T1-3-A,r:1,b:0,w:20,type:flat"));
    t.add(2, button!("T1-3-B,d:l,w:20,type:flat"));  
    w.add(t); 

    w.add(button!("OK,r:0,b:0,w:10, type: flat"));
    w.add(button!("Cancel,r:12,b:0,w:10, type: flat"));

    a.add_window(w);
    a.run();
    Ok(())
}

Button

Represent a clickable button control:

To create a button use Button::new method (with 3 parameters: a caption, a layout and initialization flags).

let b = Button::new("&Start", Layout::new("x:10,y:5,w:15"),button::Flags::None);

or the macro button!

let b1 = button!("caption=&Start,x:10,y:5,w:15");
let b2 = button!("&Start,x:10,y:5,w:15");

The caption of a button may contain the special character & that indicates that the next character is a hot-key. For example, constructing a button with the following caption &Start will set up the text of the button to Start and will set up character S as the hot key for that button (pressing Alt+S will be equivalent to pressing that button).

A button supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A button supports the following initialization types:

• button::Type::Flat or flat (for macro initialization) - thils will hide the shaddow of the button makeing it flat.

Some examples that uses these paramateres:

let disabled_button = button!("caption=&Disabled,x:10,y:5,w:15,enable=false");
let hidden_button = button!("text='&Hidden',x=9,y:1,align:center,w:9,visible=false");
let flat_button = button!("&flat,x:1,y:1,w:10,type:flat");

Events

To intercept events from a button, the following trait has to be implemented to the Window that processes the event loop:

pub trait ButtonEvents {
    fn on_pressed(&mut self, button: Handle<Button>) -> EventProcessStatus {...}
}

Methods

Besides the Common methods for all Controls a button also has the following aditional methods:

Key association

The following keys are processed by a Button control if it has focus:

Aditionally, Alt+letter or number will have the same action (even if the Button does not have a focus) if that letter or nunber was set as a hot-key for a button via its caption. For example, creating a value with the following caption: "My b&utton" (notice the & character before letter u) will enable Alt+U to be a hot-key associated with this button. Pressing this combination while the button is enabled and part of the current focused window, will change the focus to that button and will emit the ButtonEvents::on_pressed(...) event.

Example

The following code creates a window with two buttons (Add and Reset). When Add button is pressed a number is incremented and set as the text of the Add button. When Reset button is being pressed, the counter is reset to 0.

use appcui::prelude::*;

#[Window(events = ButtonEvents)]
struct MyWin {
    add: Handle<Button>,
    reset: Handle<Button>,
    counter: i32,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: Window::new("My Win", Layout::new("d:c,w:40,h:6"), window::Flags::None),
            add: Handle::None,
            reset: Handle::None,
            counter: 0,
        };
        win.add = win.add(Button::new("Add (0)", Layout::new("x:25%,y:2,w:13,a:c"), button::Type::Normal));
        win.reset = win.add(Button::new("&Reset", Layout::new("x:75%,y:2,w:13,a:c",), button::Type::Normal));
        win
    }
    fn update_add_button_caption(&mut self) {
        let h = self.add;
        let new_text = format!("Add ({})",self.counter);
        if let Some(button) = self.control_mut(h) {
            button.set_caption(new_text.as_str());
        }
    }
}

impl ButtonEvents for MyWin {
    fn on_pressed(&mut self, button_handle: Handle<Button>) -> EventProcessStatus {
        if button_handle == self.add {
            // 'Add' button was pressed - lets increment the counter
            self.counter += 1;
            self.update_add_button_caption();
            return EventProcessStatus::Processed;
        }
        if button_handle == self.reset {
            // 'Reset` button was pressed - counter will become 0
            self.counter = 0;
            self.update_add_button_caption();
            return EventProcessStatus::Processed;
        }
        // unknown handle - we'll ignore this event
        EventProcessStatus::Ignored
    }
}

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

Canvas

Represent a surface that can be drawn under a view-port:

To create a canvas use Canvas::new method (with 3 parameters: a size, a layout and initialization flags).

let b = Canvas::new(Size::new(30,10), Layout::new("x:10,y:5,w:15"),canvas::Flags::None);

or the macro canvas!

let b1 = canvas!("30x10,x:10,y:5,w:15");
let b2 = canvas!("'30,10',x:10,y:5,w:15");

A canvas supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A canvas supports the following initialization flags:

• canvas::Flags::ScrollBars or ScrollBars (for macro initialization) - thils enable a set of scrollbars that can be used to change the view of the inner surface, but only when the control has focus, as described in Components section.

Some examples that uses these paramateres:

1. A canvas with a backgroud that consists in the character X in with Aqua and DarkBlue colors.

   let c = canvas!("size:10x5,x:10,y:5,w:15,back={X,fore:aqua,back:darkblue}");
   

2. A canvas with scrollbars with different margins

   let c = canvas!("sz:'10 x 5',x:10,y:5,w:15,flags:Scrollbars,lsm:5,tsm:1");
   

Events

A canvas emits no events.

Methods

Besides the Common methods for all Controls a canvas also has the following aditional methods:

Key association

The following keys are processed by a canvas control if it has focus:

Example

The following code uses a canvas to create a viewer over the Rust language definition from wikipedia:

use appcui::prelude::*;

static text: &str = r"--- From Wiki ----
Rust is a multi-paradigm, general-purpose 
programming language that emphasizes performance, 
type safety, and concurrency. It enforces memory 
safety—meaning that all references point to valid 
memory—without a garbage collector. To 
simultaneously enforce memory safety and prevent 
data races, its 'borrow checker' tracks the object 
lifetime of all references in a program during 
compilation. Rust was influenced by ideas from 
functional programming, including immutability, 
higher-order functions, and algebraic data types. 
It is popular for systems programming.

From: https://en.wikipedia.org/wiki/Rust_(programming_language)
";
fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().size(Size::new(60,20)).build()?;
    let mut w = window!("Title,d:c,w:40,h:8,flags:Sizeable");
    let mut c = canvas!("'60x15',d:c,w:100%,h:100%,flags=ScrollBars,lsm:3,tsm:1");
    let s = c.drawing_surface_mut();
    s.write_string(0, 0, text, CharAttribute::with_color(Color::White, Color::Black), true);
    w.add(c);
    a.add_window(w);
    a.run();
    Ok(())
}

CheckBox

Represent a control with two states (checked and unckehed):

To create a checkbox use CheckBox::new method (with 3 parameters: a caption, a layout and checked status (true or false)) or method CheckBox::with_type (with one aditional parameter - the type of the checblx).

let b1 = CheckBox::new("A checkbox", 
                       Layout::new("x:10,y:5,w:15"),
                       true);
let b2 = CheckBox::with_type("Another checkbox", 
                             Layout::new("x:10,y:5,w:15"),
                             false,
                             checkbox::Type::YesNo);

or the macro checkbox!

let c1 = checkbox!("caption='Some option',x:10,y:5,w:15,h:1");
let c2 = checkbox!("'Another &option',x:10,y:5,w:15,h:1,checked:true");
let c3 = checkbox!("'&Multi-line option\nthis a hot-key',x:10,y:5,w:15,h:3,checked:false");
let c4 = checkbox!("'&YesNo checkbox',x:10,y:5,w:15,h:3,checked:false,type: YesNo");

The caption of a checkbox may contain the special character & that indicates that the next character is a hot-key. For example, constructing a checkbox with the following caption &Option number 1 will set up the text of the checkbox to Option number 1 and will set up character O as the hot key for that checkbox (pressing Alt+O will be equivalent to changing the status for that checkbox from checked to unchecked or vice-versa).

A checkbox can contain a multi-line text but you will have to set the height parameter large enough to a larger value (bigger than 1).

A checkbox supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Some examples that uses these paramateres:

let disabled_checkbox = checkbox!("caption=&Disabled,x:10,y:5,w:15,enable=false");
let hidden_checkbox = checkbox!("text='&Hidden',x=9,y:1,align:center,w:9,visible=false");
let multi_line_checkbox = checkbox!("'&Multi line\nLine2\nLine3',x:1,y:1,w:10,h:3");

The type of a checkbox is described by the checkbox::Type enum:

#![allow(unused)]
fn main() {
#[derive(Copy,Clone,PartialEq,Eq)]
pub enum Type {
    Standard, // Default value
    Ascii,
    CheckBox,
    CheckMark,
    FilledBox,
    YesNo,
    PlusMinus,
}
}

The type of the checkbox describes how the checkbox state (checked or unchecked) will be represented on the screen.

Events

To intercept events from a checkbox, the following trait has to be implemented to the Window that processes the event loop:

pub trait CheckBoxEvents {
    fn on_status_changed(&mut self, handle: Handle<CheckBox>, checked: bool) -> EventProcessStatus {...}
}

Methods

Besides the Common methods for all Controls a checkbox also has the following aditional methods:

Key association

The following keys are processed by a Checkbox control if it has focus:

Aditionally, Alt+letter or number will have the same action (even if the checkbox does not have a focus) if that letter or nunber was set as a hot-key for a checkbox via its caption.

Example

The following code creates a window with a checkbox and a label. Whenever the checkbox status is being change, the label will print the new status (checked or not-checked).

#[Window(events = CheckBoxEvents)]
struct MyWin {
    c: Handle<CheckBox>,
    l: Handle<Label>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: window!("'My Win',d:c,w:40,h:6"),
            c: Handle::None,
            l: Handle::None,
        };
        win.c = win.add(checkbox!("'My option',l:1,r:1,b:1"));
        win.l = win.add(label!("'<no status>',l:1,r:1,t:1"));
        win
    }
}

impl CheckBoxEvents for MyWin {
    fn on_status_changed(&mut self, _handle: Handle<CheckBox>, checked: bool) -> EventProcessStatus {
        let handle = self.l;
        let l = self.control_mut(handle).unwrap();
        if checked {
            l.set_caption("Status: Checked");
        } else {
            l.set_caption("Status: Not-checked");
        }
        EventProcessStatus::Processed
    }
}

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

ColorPicker

Represent a control from where you can choose a color:

To create a color picker use ColorPicker::new method (with 2 parameters: a color and a layout).

let c = ColorPicker::new(Color::Green, Layout::new("x:10,y:5,w:15"));

or the macro colorpicker!

let c1 = colorpicker!("color=Red,x:10,y:5,w:15");
let c2 = colorpicker!("Darkgreen,x:10,y:5,w:15");
let c3 = colorpicker!("Yellow,x:10,y:5,w:15,visible:false");

A ColorPicker control supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Events

To intercept events from a ColorPicker control, the following trait has to be implemented to the Window that processes the event loop:

pub trait ColorPickerEvents {
    fn on_color_changed(&mut self, handle: Handle<ColorPicker>, color: Color) -> EventProcessStatus {...}
}

Methods

Besides the Common methods for all Controls a ColorPicker control also has the following aditional methods:

Key association

The following keys are processed by a ColorPicker control if it has focus:

Example

The following example creates a Window with a ColorPicker and a label. Every time the color from the ColorPicker is being changed, the label caption will be modified with the name of the new color.

#[Window(events = ColorPickerEvents)]
struct MyWin {
    c: Handle<ColorPicker>,
    l: Handle<Label>,
}

impl MyWin {
    fn new() -> Self {
        let mut win = MyWin {
            base: Window::new("Test", Layout::new("d:c,w:40,h:10"), window::Flags::None),
            c: Handle::None,
            l: Handle::None,
        };
        win.l = win.add(label!("'',x:1,y:1,w:30,h:1"));
        win.c = win.add(colorpicker!("Black,x:1,y:3,w:30"));
        win
    }
}

impl ColorPickerEvents for MyWin {
    fn on_color_changed(&mut self, _handle: Handle<ColorPicker>, color: Color) -> EventProcessStatus {
        let h = self.l;
        if let Some(label) = self.control_mut(h) {
            label.set_caption(color.get_name());
            return EventProcessStatus::Processed;
        }
        return EventProcessStatus::Ignored;
    }
}

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

ComboBox

A combobox is a drop down list control that allows you to select a variant from a list os strings.

It can be created using ComboBox::new(...) or the combobox! macro.

let c1 = ComboBox::new(Layout::new("..."),combobox::Flags::None);
let c2 = ComboBox::new(Layout::new("..."),combobox::Flags::ShowDescription);
let c3 = combobox!("x:1,y:1,w:20,items=['Red','Greem','Blue']");
let c3 = combobox!("x:1,y:1,w:20,items=['Red','Greem','Blue'],index:2");

A combobox supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A combobox supports the following initialization flags:

• combobox::Flags::ShowDescription or ShowDescription (for macro initialization) - thils will allow a combobox show the description of each item (if exists) when expanded

Events

To intercept events from a combobox, the following trait has to be implemented to the Window that processes the event loop:

pub trait ComboBoxEvents {
    fn on_selection_changed(&mut self, handle: Handle<ComboBox>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

Methods

Besides the Common methods for all Controls a combobox also has the following aditional methods:

Remarks: Methods selected_item and seletec_item_mut return an Option over the type combobox::Item that is defined as follows:

pub struct Item { ...}

impl Item {
    pub fn new(value: &str, description: &str) -> Self {...}
    pub fn from_string(value: String, description: String) -> Self {...}
    pub fn set_value(&mut self, value: &str) {...}
    pub fn value(&self) -> &str {...}
    pub fn set_description(&mut self, description: &str) {...}
    pub fn description(&self) -> &str {...}
}

Key association

The following keys are processed by a ComboBox control if it has focus:

Besides this using any one of the following keys: A to Z and/or 0 to 9 will move the selection to the fist variant that starts with that letter (case is ignored). The search starts from the next variant after the current one. This means that if you have multiple variants that starts with letter G, pressing G multiple times will efectively switch between all of the variants that starts with letter G.

When the combobox is expanded the following additional keys can be used:

Example

The following example creates a Window with a ComboBox that was populated with various animals and their speed. Selecting one animal from the list changes the title of the window to the name of that animal.

use appcui::prelude::*;

#[Window(events = ComboBoxEvents)]
struct MyWin {}
impl MyWin {
    fn new() -> Self {
        let mut w = Self {
            base: window!("x:1,y:1,w:34,h:6,caption:Win"),
        };
        w.add(label!("'Select animal',x:1,y:1,w:30"));
        let mut c = ComboBox::new(Layout::new("x:1,y:2,w:30"), combobox::Flags::ShowDescription);
        // data from https://en.wikipedia.org/wiki/Fastest_animals
        c.add_item(combobox::Item::new("Cheetah","(120 km/h)"));
        c.add_item(combobox::Item::new("Swordfish","(97 km/h)"));
        c.add_item(combobox::Item::new("Iguana","(35 km/h)"));
        c.add_item(combobox::Item::new("Gazelle","(81 km/h)"));
        c.add_item(combobox::Item::new("Lion","(80 km/h)"));
        c.add_item(combobox::Item::new("Dog","(60 km/h)"));
        c.add_item(combobox::Item::new("Zebra","(56 km/h)"));
        w.add(c);
        w
    }
}
impl ComboBoxEvents for MyWin {
    fn on_selection_changed(&mut self, handle: Handle<ComboBox>) -> EventProcessStatus {
        let title = if let Some(cb) = self.control_mut(handle) {
            if let Some(item) = cb.selected_item() {
                item.value().to_string()
            } else {
                String::from("[None]")
            }
        } else {
            String::from("?")
        };
        self.set_title(&title);
        EventProcessStatus::Processed
    }
}


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

DatePicker

Represent a control from where you can choose a color:

To create a color picker use DatePicker::new method (with 2 parameters: a date and a layout), or it can be created with DatePicker::with_date method (with 2 parameters: a NaiveDate object and a layout).

let d = DatePicker::new("2024-06-13", Layout::new("d:c,w:19"));
let d = DatePicker::with_date(NaiveDate::from_ymd_opt(2000, 10, 1).unwrap(), Layout::new("d:c,w:19"));

or the macro datepicker!

let d1 = datepicker!("2024-06-13,x:1,y:1,w:19");
let d2 = datepicker!("date:2024-06-13,x:1,y:1,w:19");

A DatePicker control supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Events

To intercept events from a DatePicker control, the following trait has to be implemented to the Window that processes the event loop:

pub trait DatePickerEvents {
    fn on_date_change(&mut self, _handle: Handle<DatePicker>, date: chrono::prelude::NaiveDate) -> EventProcessStatus {...}
}

Methods

Besides the Common methods for all Controls a DatePicker control also has the following aditional methods:

Key association

The following keys are processed by a DatePicker control if it has focus:

On unexpanded calendar:

On expanded calendar:

On both calendar types:

Example

The following example creates a Window with a DatePicker. The window implements the DatePickerEvents to intercept DatePicker events.

use appcui::prelude::*;

use appcui::prelude::*;

#[Window(events=DatePickerEvents)]
struct MyWin {
    dp: Handle<DatePicker>,
}

impl MyWin{
    fn new() -> Self{
        let mut win = MyWin{
            base: window!("Dates,d:c,w:25,h:6"),
            dp: Handle::None,
        };
        win.dp = win.add(datepicker!("2024-06-13,x:1,y:1,w:19"));
        win
    }

}

impl DatePickerEvents for MyWin{
    fn on_date_change(&mut self, _handle: Handle<DatePicker>, date: chrono::prelude::NaiveDate) -> EventProcessStatus {
        self.base.set_title(&format!("Date: {}", date));
        EventProcessStatus::Processed                                                                        
    }
}

fn main(){
    let mut a =  App::new().build().unwrap();
    a.add_window(MyWin::new());
    a.run();
}

DropDownList

A drop down list is a templetize (generics based) control that allows you to select a variant of a list of variants of type T.

It can be create using DropDownList::new(...) , DropDownList::with_symbol(...) or the dropdownlist! macro. Using DropDownList::new(...) and DropDownList::with_symbol(...) can be done in two ways:

1. by specifying the type for a variable:

   let s: DropDownList<T> = DropDownList::new(...);
   

2. by using turbo-fish notation (usually when you don't want to create a separate variable for the control):

   let s = DropDownList::<T>::with_symbol(...);
   

Remarks: It is important to notice that the T type must implement a special trait DropDownListType that is defined as follows:

pub trait DropDownListType {
    fn name(&self) -> &str;
    fn description(&self) -> &str {
        ""
    }
    fn symbol(&self) -> &str {
        ""
    }
}

where:

• name() is a method that provides a string representation (name) for a specific variant
• description() is a method that provides a detailed description for a specific variant
• symbol() is a method that returns a suggested symbol for a specific variant

Examples

Assuming we have the following struct: MyData thet implements the required traits as follows:

struct MyData { ... }
impl DropDownListType for MyData { ... }

then we can create a dropdown list object based on this type as follows:

let d1: DropDownList<MyData> = DropDownList::new(Layout::new("..."),dropdownlist::Flags::None);

let d2: DropDownList<MyData> = DropDownList::with_symbol(1,Layout::new("..."),dropdownlist::Flags::AllowNoneSelection);

let d3 = dropdownlist!("class:MyData,x:1,y:1,w:20");

let d4 = dropdownlist!("class:MyData,x:1,y:1,w:20, flags: AllowNoneSelection, symbolsize:1");

let d5 = dropdownlist!("MyData,x:1,y:1,w:20");

A dropdown list supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A dropdown list supports the following initialization flags:

• dropdownlist::Flags::AllowNoneSelection or AllowNoneSelection (for macro initialization) - thils will allow a dropdown list to hold a None value (meaning that the user can select no variant)
• dropdownlist::Flags::ShowDescription or ShowDescription (for macro initialization) - this will show the description of the selected variant in the dropdown list

Events

To intercept events from a dropdown list, the following trait has to be implemented to the Window that processes the event loop:

pub trait DropDownListEvents<T> {
    fn on_selection_changed(&mut self, handle: Handle<DropDownList<T>>) -> EventProcessStatus {...}
}

Methods

Besides the Common methods for all Controls a dropdown list also has the following aditional methods:

Key association

The following keys are processed by a DropDownList control if it has focus:

Besides this using any one of the following keys: A to Z and/or 0 to 9 will move the selection to the fist variant that starts with that letter (case is ignored). The search starts from the next variant after the current one. This means that if you have multiple variants that starts with letter G, pressing G multiple times will efectively switch between all of the variants that starts with letter G.

When the dropdown list is expanded the following additional keys can be used:

Example

The following example creates a Window with a DropDownList from where we can select a symbol: ♥ or ♠.

use appcui::prelude::*;

struct MyObject {
    name: String,
    description: String,
    symbol: String,
}

impl MyObject {
    fn new(name: &str, description: &str, symbol: &str) -> MyObject {
        MyObject {
            name: name.to_string(),
            description: description.to_string(),
            symbol: symbol.to_string(),
        }
    }
}

impl DropDownListType for MyObject {
    fn name(&self) -> &str {
        &self.name
    }
    fn description(&self) -> &str {
        &self.description
    }
    fn symbol(&self) -> &str {
        &self.symbol
    }
}

fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().build()?;
    let mut w = window!("x:1,y:1,w:60,h:20,title:Win");
    let mut db = DropDownList::<MyObject>::with_symbol(1, Layout::new("x:1,y:1,w:56"), dropdownlist::Flags::ShowDescription);
    db.add(MyObject::new("Heart", "(symbol of love)", "♥"));
    db.add(MyObject::new("Spade", "(used in a deck of cards)", "♠"));
    w.add(db);
    a.add_window(w);
    a.run();
    Ok(())
}

Label

Represent a label (a text):

To create a label use Label::new method (with 2 parameters: a caption and a layout).

let b = Label::new("My label", Layout::new("x:10,y:5,w:15"));

or the macro label!

let l1 = label!("caption='a caption for the label',x:10,y:5,w:15");
let l2 = label!("MyLabel,x:10,y:5,w:15");

The caption of a label may contain the special character & that indicates that the next character is a hot-key. However, as a label can not receive any input, the hotkey is meant to be for display only.

A label supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Events

A label emits no events.

Methods

Besides the Common methods for all Controls a label also has the following aditional methods:

Key association

A label does not receive any input and as such it has no key associated with it.

Example

The following code creates a window with a label that contains the text Hello world !.

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut w = Window::new("Title", Layout::new("d:c,w:40,h:9"), window::Flags::None);
    w.add(Label::new("Hello world !", Layout::new("d:c,w:14,h:1")));
    app.add_window(w);
    app.run();
    Ok(())
}

ListBox

A listbox is a control that displays a list of items.

It can be created using ListBox::new(...) and ListBox::with_capacity(...) methods or with the listbox! macro.

let l1 = ListBox::new(Layout::new("..."),listbox::Flags::None);
let l2 = ListBox::with_capacity(10,Layout::new("..."),listbox::Flags::ScrollBars);
let l3 = listbox!("x:1,y:1,w:20,h:10,items=['Red','Greem','Blue']");
let l4 = listbox!("x:1,y:1,w:20,h:10,items=['Red','Greem','Blue'],index:2");
let l5 = listbox!("x:1,y:1,w:20,h:10,items=['Red','Greem','Blue'],index:2, flags: ScrollBars+SearchBar");

A listbox supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A listbox supports the following initialization flags:

• listbox::Flags::ScrollBars or ScrollBars (for macro initialization) - this enables a set of scrollbars that can be used to navigate through the list of items. The scrollbars are visible only when the control has focus
• listbox::Flags::SearchBar or SearchBar (for macro initialization) - this enables a search bar that can be used to filter the list of items. The search bar is visible only when the control has focus
• listbox::Flags::CheckBoxes or CheckBoxes (for macro initialization) - this enable a set of checkboxes that can be used to select multiple items from the list.
• listbox::Flags::AutoScroll or AutoScroll (for macro initialization) - this will automatically scroll the listbox to the last item whenever a new item is being added. This flag is usefull for scenarios where the listbox is used as a log/event viewer.
• listbox::Flags::HighlightSelectedItemWhenInactive or HighlightSelectedItemWhenInactive (for macro initialization) - this will highlight the selected item even when the listbox does not have focus. This flag is usefull when the listbox is used as a navigation menu.

Events

To intercept events from a listbox, the following trait has to be implemented to the Window that processes the event loop:

pub trait ListBoxEvents {
    fn on_current_item_changed(&mut self, handle: Handle<ListBox>, index: usize) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
    fn on_item_checked(&mut self, handle: Handle<ListBox>, index: usize, checked: bool) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

Methods

Besides the Common methods for all Controls a listbox also has the following aditional methods:

An item from the ListBox is represented by the following structure:

pub struct Item { ...}

impl Item {
    pub fn new(text: &str, checked: bool) -> Self {...}
    pub fn text(&self) -> &str {...}
    pub fn is_checked(&self) -> bool {...}
}

Key association

The following keys are processed by a ListBox control if it has focus:

When pressing an ascii key, the ListBox will start a search in the list of items. All items that are matched (ignoring case) will be highlighted while the rest of them will be dimmed. While in search mode, the following keys can be used to navigate through the list of items:

Any other key used while in search mode (such as arrow keys, page up, page down, etc) will exit the search mode and will be processed as a normal key press.

Example

The following example creates a Window with a ListBox that was populated with various animals.

use appcui::prelude::*;


fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().build()?;
    let mut w = window!("Animals,d:c,w:50,h:11,flags: Sizeable");
    let mut p = panel!("l:1,t:1,b:1,r:1");
    let mut l = listbox!("d:c,w:100%,h:100%,flags: ScrollBars+CheckBoxes+SearchBar, lsm:2");
    l.add_item(listbox::Item::new("Dog (man best friend)", false));
    l.add_item(listbox::Item::new("Cat (independent)", true));
    l.add_item(listbox::Item::new("Elephant (the largest land animal)", false));
    l.add_item(listbox::Item::new("Giraffe (the tallest animal, can reach 5.5m)", true));
    l.add_item(listbox::Item::new("Lion (the king of the jungle)", false));
    l.add_item(listbox::Item::new("Tiger (the largest cat species)", false));
    l.add_item(listbox::Item::new("Zebra (black and white stripes)", false));
    l.add_item(listbox::Item::new("Donkey (related to horses)", false));
    l.add_item(listbox::Item::new("Cow (provides milk)", false));
    p.add(l);
    w.add(p);
    a.add_window(w);
    a.run();
    Ok(())
}

ListView

A ListView is a templetize (generics based) control that allows you to view a list of objects.

It can be created using ListView::new(...) and ListView::with_capacity(...) methods or with the listview! macro.

let l1: ListView<T> = ListView::new(Layout::new("..."),listview::Flags::None);
let l2: ListView<T> = ListView::with_capacity(10,Layout::new("..."),listview::Flags::ScrollBars);
let l3 = listview!("class: T, flags: Scrollbar, d:c, w:100%, h:100%");
let l4 = listview!("type: T, flags: Scrollbar, d:c, view:Columns(3)");
let l5 = listview!("T, d:c, view:Details, columns:[{Name,10,left},{Age,5,right},{City,20,center}]");

where type T is the type of the elements that are shown in the list view and has to implement ListItem trait.

A listview supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

The field columns is a list of columns that are displayed in the ListView control. Each column is a tuple with three elements: the name of the column, the width of the column in characters, and the alignment of the column (left, right, or center). The column field accespts the following parameters:

To create a column with the name Test, that hast Ctrl+E assigned as a hot key, with a width of 10 characters, and aligned to the right, you can use the following formats:

• {caption: "T&est", width: 10, align: right}
• {name: "T&est", w: 10, a: right}
• {T&est, 10, right}
• {T&est,10,r}

Similary, to create a listview with 3 columns (Name, Age, and City) with the widths of 10, 5, and 20 characters, respectively, and aligned to the left, right, and center, you can use the following format:

let l = listview!("T, d:c, view:Details, columns:[{Name,10,left},{Age,5,right},{City,20,center}]");

A listview supports the following initialization flags:

• listview::Flags::ScrollBars or ScrollBars (for macro initialization) - this enables a set of scrollbars that can be used to navigate through the list of items. The scrollbars are visible only when the control has focus
• listview::Flags::SearchBar or SearchBar (for macro initialization) - this enables a search bar that can be used to filter the list of items. The search bar is visible only when the control has focus
• listview::Flags::CheckBoxes or CheckBoxes (for macro initialization) - this enable a set of checkboxes that can be used to select multiple items from the list.
• listview::Flags::ShowGroups or ShowGroups (for macro initialization) - this enables the grouping of items in the list view.
• listview::Flags::SmallIcons or SmallIcons (for macro initialization) - this enables the small icons (one character) view mode for the list view.
• listview::Flags::LargeIcons or LargeIcons (for macro initialization) - this enables the large icons (two characters or unicode surrogates) view mode for the list view.
• listview::Flags::CustomFilter or CustomFilter (for macro initialization) - this enables the custom filter that can be used to filter the list of items. The custom filter should be provided by the user in the ListItem implementation.
• listview::Flags::NoSelection or NoSelection (for macro initialization) - this disables the selection of items from the list view. This flag is useful when the list view is used only for displaying information and the selection is not needed (such as a Save or Open file dialog). Using this flag together with the CheckBoxes flag will result in a panic.

Events

To intercept events from a listview, the following trait has to be implemented to the Window that processes the event loop:

pub trait ListViewEvents<T: ListItem + 'static> {
    // called when the current item is changed
    fn on_current_item_changed(&mut self, handle: Handle<ListView<T>>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
    
    // called when a group (if groups are enabled) is collapsed
    fn on_group_collapsed(&mut self, handle: Handle<ListView<T>>, group: listview::Group) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }

    // called when a group (if groups are enabled) is expanded
    fn on_group_expanded(&mut self, handle: Handle<ListView<T>>, group: listview::Group) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }

    // called when the selection is changed
    fn on_selection_changed(&mut self, handle: Handle<ListView<T>>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }

    // called when you double click on an item (or press Enter)
    fn on_item_action(&mut self, handle: Handle<ListView<T>>, item_index: usize) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

Methods

Besides the Common methods for all Controls a list view also has the following aditional methods:

Adding items and groups

Item manipulation

Group manipulation

Column manipulation

Miscellaneous

Key association

The following keys are processed by a ListView control if it has focus: