Struct InputAppBuilder 

pub struct InputAppBuilder<T: InputApp + 'static> { /* private fields */ }

Builder for an input-driven AppCUI application.

Obtain this builder with App::input_app. Configure close behavior, the clear character, and the terminal, then call run to start the event loop.

Examples

use appcui::prelude::*;

struct HelloWorld;
impl InputApp for HelloWorld {
    fn on_paint(&self, surface: &mut Surface) {
        surface.write_string(0, 0, "Hello World !", charattr!("white"), false);
    }
}

fn main() -> Result<(), appcui::system::Error> {
    App::input_app(HelloWorld {})
        .title("Hello")
        .run()
}

Implementations

impl<T: InputApp + 'static> InputAppBuilder<T>

pub fn auto_close(self, value: bool) -> Self

Enables or disables closing the application with the Escape key.

When enabled (the default), pressing Escape calls App::close. When disabled, Escape is forwarded to InputApp::on_key_event.

Parameters

• value - true to close on Escape, false to handle it yourself.

Examples

use appcui::prelude::*;

struct HelloWorld;
impl InputApp for HelloWorld {
    fn on_paint(&self, _surface: &mut Surface) {}
}

App::input_app(HelloWorld {}).auto_close(false);

pub fn clear_char(self, ch: Option<Character>) -> Self

Sets the character used to clear the surface before each paint.

The default is a space with a white foreground and black background. Pass None to skip the fill and only reset clip and origin.

Parameters

• ch - The clear character, or None to leave the previous frame in place.

Examples

use appcui::prelude::*;

struct HelloWorld;
impl InputApp for HelloWorld {
    fn on_paint(&self, _surface: &mut Surface) {}
}

App::input_app(HelloWorld {}).clear_char(Some(char!("' ',white,black")));

pub fn run(self) -> Result<(), Error>

Builds the application from the current settings and starts the event loop.

This method consumes the builder, creates the runtime, and blocks until the application closes. InputApp::on_paint is called whenever the runtime requests a redraw.

Errors

Returns crate::system::Error if the application cannot be initialized (for example, if another application is already running).

pub fn size(self, terminal_size: Size) -> Self

Sets the size of the terminal in character cells.

If not specified, the backend uses the current terminal size (or a backend-specific default).

Parameters

• terminal_size - Width and height of the terminal, in character cells.

Examples

use appcui::prelude::*;

App::new().size(Size::new(80, 25));

pub fn title(self, title: &str) -> Self

Sets the title shown by the terminal window or browser tab.

Support depends on the selected backend. If not specified, a backend default title is used.

Parameters

• title - The application title.

Examples

use appcui::prelude::*;

App::new().title("My Application");

pub fn log_file(self, name: &str, append: bool) -> Self

Sets the log file used when the crate is compiled in debug mode.

This option has no effect in release builds.

Parameters

• name - Path of the log file.
• append - If true, new logs are appended; if false, the file is overwritten.

Examples

use appcui::prelude::*;

App::new().log_file("appcui.log", false);

pub fn color_schema(self, enabled: bool) -> Self

Enables or disables the terminal color schema.

When enabled (the default), the backend may map AppCUI colors through the terminal’s color schema. Disable this to keep the exact colors defined by the theme.

Parameters

• enabled - true to use the terminal color schema, false to disable it.

Examples

use appcui::prelude::*;

App::new().color_schema(false);

pub fn restore_screen(self, enable: bool) -> Self

Controls whether the original screen is restored when the application ends.

When enabled (the default), the backend attempts to restore the original screen content and cursor position. When disabled, the screen is cleared on exit.

Parameters

• enable - true to restore the original screen, false to clear it.

Remarks

Not all backends can restore the original screen. Backends without this support always clear the screen when the application ends.

Examples

use appcui::prelude::*;

App::new().restore_screen(false);

pub fn backend(self, backend: Type) -> Self

Selects the terminal backend used to render the application.

If not specified, AppCUI picks a backend appropriate for the current platform and enabled crate features.

Parameters

• backend - The crate::backend::Type to use.

Examples

use appcui::prelude::*;

#[cfg(target_os = "windows")]
let _builder = App::new().backend(appcui::backend::Type::WindowsVT);
#[cfg(not(target_os = "windows"))]
let _builder = App::new();

pub fn debug_script(self, script: &str) -> Self

Configures a debug script that simulates input for unit tests.

Each line of script is a command executed in order against a virtual terminal. After the last command the application ends.

Combine this method with size to set the simulated terminal dimensions (width and height).

Parameters

• script - Commands to execute, one per line.

Debug commands

Mouse related commands

• Mouse.Hold(x,y,button) simulates an event where the mouse button is being pressed while the mouse is located at a specific position on screen. The parameters x and y are a screen position, while the parameter button is one of left, right or center
• Mouse.Release(x,y) simulates the release of all mouse buttons while the mouse is located at a specific screen position.
• Mouse.Click(x,y,button) simulates a click (hold an release)
• Mouse.Move(x,y) simulates the movement of a mouse to coordonates (x,y). No mouse button are being pressed.
• Mouse.Drag(x1,y1,x2,y2) simulates the movement of a mouse from (x1,y1) to (x2,y2) while the left button is being pressed
• Mouse.Wheel(x,y,direction,times) simulates the wheel mouse being rotated into a direction (one of top, bottom, left, right) for a number of times. The times parameter must be biggen than 0.

Key related commands

• Key.Pressed(key) where key can be any combination of keys

Paint related commands

• Paint(name) paints the current virtual screen into the current screen using ANSI codes.
• Paint.Enable(value) enables or disables painting. value is a boolean value (true or false). If set to false all subsequent calls to command Paint will be ignored.

System events

• Resize(width,height) simulates a resize of the virtual terminal to the size represented by width and height parameters

Validation commands

• CheckHash(hash) checks if the hash computer over the current virtual screen is as expected. If not it will panic. This is useful for unit testing.

Examples

use appcui::prelude::*;

let script = "
    Paint(initial)
    Key.Pressed(Escape)
";
App::new()
    .size(Size::new(60, 10))
    .debug_script(script)
    .window(|| window!("'Test',a:c,w:20,h:6"));