Struct Boxy 

pub struct Boxy<'a> { /* private fields */ }

The main struct that represents a text box for CLI display.

Boxy contains all the configuration and content needed to render a styled text box in the terminal, including borders, text content, colors, padding, and alignment options.

Examples

use boxy_cli::prelude::*;

// Create a simple text box
let mut my_box = Boxy::new(BoxType::Double, "#00ffff");
my_box.add_text_sgmt("Hello, World!", "#ffffff", BoxAlign::Center);
my_box.display();

Implementations

impl<'a> Boxy<'a>

pub fn new(box_type: BoxType, box_color: &str) -> Self

Creates a new instance of the Boxy struct with the specified border type and color.

Arguments

• box_type - The border style to use from the BoxType enum
• box_color - Hex color code (e.g. \"#ffffff\") for the border. Falls back to white with a stderr warning on invalid input

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Double, "#00ffff");

pub fn builder() -> BoxyBuilder<'a>

Returns a new BoxyBuilder to create a text box using the builder pattern.

The builder pattern provides a more fluent interface for configuring and creating a Boxy instance.

Examples

use boxy_cli::prelude::*;

let my_box = Boxy::builder()
    .box_type(BoxType::Double)
    .color("#00ffff")
    .add_segment("Hello, World!", "#ffffff", BoxAlign::Center)
    .build();

pub fn add_text_sgmt( &mut self, data_string: &str, color: &str, text_align: BoxAlign, )

Adds a new plain-text segment to the box, separated from previous segments by a horizontal divider.

Each call creates one distinct segment. Text is automatically word-wrapped to fit the available width. For additional lines within the same segment (no divider between them), use add_text_line after this call.

Arguments

• data_string - The text content for this segment
• color - Hex color code (e.g. \"#ffffff\") for the text. Falls back to white with a stderr warning on invalid input
• text_align - How text is aligned within this segment: left, center, or right

Examples

use boxy_cli::prelude::*;

let mut b = Boxy::new(BoxType::Single, "#00ffff");
b.add_text_sgmt("Header", "#ffffff", BoxAlign::Center);
b.add_text_sgmt("Body text below a divider", "#aaaaaa", BoxAlign::Left);
b.display();

pub fn add_col_text_sgmt(&mut self, text_align: BoxAlign, column_count: usize)

Adds a new columnar segment to the text box, separated by a horizontal divider.

This sets up an empty segment with column_count side-by-side columns. Unlike add_text_sgmt, it doesn’t take any text content directly — columns start out empty and are populated afterwards with add_col_text_line or add_col_text_line_indx. By default, all columns are given equal width; use set_segment_ratios to customize the width ratio between columns.

Arguments

• text_align - The alignment (left, center, right) applied to text within each column
• column_count - The number of columns in this segment (must be at least 1)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.add_col_text_sgmt(BoxAlign::Left, 2);
my_box.add_col_text_line("Left column text", "#ffffff", &0usize);
my_box.add_col_text_line("Right column text", "#ffffff", &1usize);

Panics

Panics if column_count is 0.

pub fn add_text_line_indx( &mut self, data_string: &str, color: &str, seg_index: usize, )

Adds a new text line to the segment with a specific index.

This method allows adding additional lines of text to an existing segment by specifying the segment’s index. The new line will appear below the existing content in that segment.

Arguments

• data_string - The text content to add
• color - Hex color code (e.g. \"#ffffff\") for the text. Falls back to white with a stderr warning on invalid input
• seg_index - The index of the segment to add this line to (0-based)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.add_text_sgmt("First segment", "#ffffff", BoxAlign::Left);
my_box.add_text_sgmt("Second segment", "#ffffff", BoxAlign::Left);

// Add a line to the first segment (index 0)
my_box.add_text_line_indx("Additional line in first segment", "#32CD32", 0);

Panics

Panics if seg_index is out of bounds, or if the segment at that index is a columnar segment — use add_col_text_line_indx for those.

pub fn add_col_text_line_indx( &mut self, data_string: &str, color: &str, seg_index: &usize, col_index: &usize, )

Adds a new line of text to a specific column within a specific columnar segment.

This mirrors add_text_line_indx, but targets a single column inside a columnar segment created via add_col_text_sgmt. Each column accumulates its own independent list of lines, stacked top-to-bottom within that column.

Arguments

• data_string - The text content to add
• color - Hex color code (e.g. \"#ffffff\") for the text. Falls back to white with a stderr warning on invalid input
• seg_index - The index of the columnar segment to add this line to (0-based)
• col_index - The index of the column within that segment to add this line to (0-based)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.add_col_text_sgmt(BoxAlign::Left, 2);

// Add a line to column 0, then another to column 1
my_box.add_col_text_line_indx("Name: Alice", "#ffffff", &0usize, &0usize);
my_box.add_col_text_line_indx("Name: Bob", "#ffffff", &0usize, &1usize);

Note

If columns within the same segment have different numbers of lines, shorter columns are padded with blank rows to match the height of the tallest one. This happens automatically at render time — you do not need to add blank lines manually.

Panics

Panics if:

• seg_index is out of bounds
• The segment at seg_index is not a columnar segment
• col_index is out of bounds for that segment’s column count

pub fn add_text_line(&mut self, data_string: &str, color: &str)

Adds a new line of text to the most recently added segment.

This is a convenience method that adds a line to the last segment created, eliminating the need to specify the segment index. The new line appears below existing content in that segment with no divider between them.

Arguments

• data_string - The text content to add
• color - Hex color code (e.g. \"#ffffff\") for the text. Falls back to white with a stderr warning on invalid input

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.add_text_sgmt("Header", "#ffffff", BoxAlign::Center);
my_box.add_text_line("Additional details below the header", "#32CD32");

Panics

Panics if no segments have been added yet, or if the last segment is a columnar segment — use add_col_text_line for those.

pub fn add_col_text_line( &mut self, data_string: &str, color: &str, col_index: &usize, )

Adds a new line of text to a specific column within the most recently added segment.

This is a convenience method that mirrors add_text_line, but for columnar segments: it adds a line to a column of the last segment that was created, eliminating the need to specify the segment index.

Arguments

• data_string - The text content to add
• color - Hex color code (e.g. \"#ffffff\") for the text. Falls back to white with a stderr warning on invalid input
• col_index - The index of the column within the last segment to add this line to (0-based)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.add_col_text_sgmt(BoxAlign::Left, 2);
my_box.add_col_text_line("Left column text", "#ffffff", &0usize);
my_box.add_col_text_line("Right column text", "#ffffff", &1usize);

Note

If columns within the same segment have different numbers of lines, shorter columns are padded with blank rows to match the height of the tallest one. This happens automatically at render time — you do not need to add blank lines manually.

Panics

Panics if no segments have been added yet, if the last segment is not a columnar segment, or if col_index is out of bounds for that segment’s column count.

pub fn set_align(&mut self, align: BoxAlign)

Sets the overall alignment of the box within the terminal.

This controls where the box is positioned horizontally on screen, not the alignment of text inside it (which is set per-segment).

Behaviour with external padding

When set to BoxAlign::Center, the box is positioned at the true center of the terminal. External left/right padding is still used to determine the box width (more padding → narrower box), but the resulting box is always centerd — the padding values do not shift it left or right. As long as the terminal is wide enough, external padding is effectively a width constraint rather than a margin.

Arguments

• align - The alignment to use: BoxAlign::Left, BoxAlign::Center, or BoxAlign::Right

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.set_align(BoxAlign::Center); // center the box in the terminal

use boxy_cli::prelude::*;

// External padding shrinks the box but does not shift it off-center
let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.set_align(BoxAlign::Center);
my_box.set_ext_padding(BoxPad::uniform(5)); // box is 10 chars narrower, still centerd

pub fn set_int_padding(&mut self, int_padding: BoxPad)

Sets the internal padding between the text box border and its text content.

Internal padding creates space between the border of the box and the text inside it.

Arguments

• int_padding - A BoxPad instance specifying the padding values

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");

// Set uniform padding of 2 spaces on all sides
my_box.set_int_padding(BoxPad::uniform(2));

// Or set different padding for each side (top, left, down, right)
my_box.set_int_padding(BoxPad::from_tldr(1, 3, 1, 3));

pub fn set_ext_padding(&mut self, ext_padding: BoxPad)

Sets the external padding between the terminal edges and the text box.

External padding creates space between the terminal edge and the box border, which affects both positioning (for BoxAlign::Left and BoxAlign::Right) and box width.

Behaviour with center alignment

When the box alignment is BoxAlign::Center, left and right external padding values affect the width of the box (larger padding → narrower box) but do not shift its position. The box always occupies the center of the terminal regardless of the padding values set here, as long as the terminal is wide enough. Top and bottom padding always behave as blank lines regardless of alignment.

Arguments

• ext_padding - A BoxPad instance specifying the padding values

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.set_ext_padding(BoxPad::uniform(5));

use boxy_cli::prelude::*;

// With center alignment, padding shrinks the box but keeps it centerd
let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.set_align(BoxAlign::Center);
my_box.set_ext_padding(BoxPad::from_tldr(1, 10, 1, 10)); // 20 chars narrower, still centerd

pub fn set_padding(&mut self, ext_padding: BoxPad, int_padding: BoxPad)

Sets both internal and external padding for the text box in a single call.

This is a convenience method that combines set_int_padding and set_ext_padding.

/// # Note

See set_align for how external padding interacts with BoxAlign::Center.

Arguments

• ext_padding - A BoxPad instance for the external padding (between terminal edges and box)
• int_padding - A BoxPad instance for the internal padding (between box border and text)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");

// Set both internal and external padding
my_box.set_padding(
    BoxPad::from_tldr(1, 5, 1, 5), // external padding
    BoxPad::uniform(2)            // internal padding
);

pub fn set_width(&mut self, width: usize)

Sets a fixed width for the box instead of dynamically sizing to the terminal.

The width value includes the two border characters, so the usable inner text area is width - 2 columns (minus any internal padding on top of that). Setting width to 0 returns to dynamic terminal-width sizing.

Arguments

• width - Total box width in terminal columns, including border characters

Examples

use boxy_cli::prelude::*;

let mut b = Boxy::new(BoxType::Single, "#00ffff");
b.set_width(60); // 60 total columns: 2 borders + 58 usable
b.add_text_sgmt("Fixed width box", "#ffffff", BoxAlign::Center);
b.display();

pub fn set_height(&mut self, height: usize)

Sets a fixed height for the text box by adding whitespace above and below the text.

Arguments

• height - The desired height in characters (including borders)

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Single, "#00ffff");
my_box.set_height(20); // Set box height to 20 lines

Note

This feature is experimental and may not work as expected in the current version. Setting height to 0 returns to dynamic sizing based on content.

pub fn set_type(&mut self, box_type: BoxType)

Sets the border style for the box.

Can be called at any point, including after segments have been added. Takes effect on the next call to display.

Arguments

• box_type - The border style from the BoxType enum

Examples

use boxy_cli::prelude::*;

let mut b = Boxy::new(BoxType::Single, "#00ffff");
b.add_text_sgmt("Hello", "#ffffff", BoxAlign::Center);
b.set_type(BoxType::Double); // switch to double borders before displaying
b.display();

pub fn set_color(&mut self, color: &str)

Sets the border color using a hex color code.

Can be called at any point before display. On an invalid hex string, falls back to white and prints a warning to stderr.

Arguments

• color - Hex color code (e.g. \"#ffffff\"). Falls back to white with a stderr warning on invalid input

Examples

use boxy_cli::prelude::*;

let mut b = Boxy::new(BoxType::Single, "#00ffff");
b.set_color("#ff0000"); // change border to red

pub fn set_segment_ratios(&mut self, seg_index: usize, ratios: Vec<usize>)

Sets the column width ratios for a columnar segment.

Ratios are relative — vec![1, 2, 1] gives the middle column twice the width of the others. The number of ratios must exactly match the column count the segment was created with.

If this is never called, columns default to equal widths (equivalent to vec![1; column_count]).

Arguments

• seg_index - Zero-based index of the columnar segment to configure
• ratios - One ratio value per column; values are relative, not absolute

Panics

Panics if:

• seg_index is out of bounds
• The segment at seg_index is a Single text segment, not columnar
• The length of ratios does not match the column count of the segment

Examples

use boxy_cli::prelude::*;

let mut b = Boxy::new(BoxType::Single, "#00ffff");
b.add_col_text_sgmt(BoxAlign::Left, 3);
// Give the last column twice the space of the first two
b.set_segment_ratios(0, vec![1, 1, 2]);

pub fn display(&mut self)

Renders and displays the text box in the terminal.

Automatically sizes the box to the current terminal width unless a fixed width has been set via set_width. Call this after all segments and configuration are set — subsequent calls re-render with the current terminal size, so the box will adapt if the terminal was resized between calls.

Output uses ANSI true-color escape codes. Terminals without true-color support will fall back gracefully to the nearest available color via the colored crate. On terminals with NO_COLOR set or where color is disabled, plain text is emitted.

Examples

use boxy_cli::prelude::*;

let mut my_box = Boxy::new(BoxType::Double, "#00ffff");
my_box.add_text_sgmt("Hello, World!", "#ffffff", BoxAlign::Center);
my_box.display();

Trait Implementations

impl<'a> Debug for Boxy<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Boxy<'_>

fn default() -> Self

Returns the “default value” for a type.