Struct BoxyBuilder 

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

The BoxyBuilder struct implements a fluent builder pattern for creating Boxy instances.

This builder provides a more expressive and readable way to create and configure text boxes. Each method returns the builder instance itself, allowing method calls to be chained together. When the configuration is complete, call the build() method to create the actual Boxy instance.

Examples

use boxy_cli::prelude::*;

// Create and display a text box in a single fluent sequence
Boxy::builder()
    .box_type(BoxType::Double)
    .color("#00ffff")
    .padding(BoxPad::uniform(1), BoxPad::from_tldr(2, 2, 1, 1))
    .align(BoxAlign::Center)
    .add_segment("Hello, Boxy!", "#ffffff", BoxAlign::Center)
    .add_line("This is a new line.", "#32CD32")
    .add_segment("Another section", "#663399", BoxAlign::Left)
    .width(50)
    .build()
    .display();

Implementations

impl<'a> BoxyBuilder<'a>

pub fn new() -> Self

Creates a new BoxyBuilder with default values.

This creates a builder with the following default values:

• Box type: BoxType::Single
• Color: empty string (will use white if not set)
• Padding: zero on all sides
• Alignment: BoxAlign::Left
• No text segments

Examples

use boxy_cli::prelude::*;

let builder = BoxyBuilder::new();
// Configure the builder with various methods
let my_box = builder.box_type(BoxType::Double)
                   .color("#00ffff")
                   .build();

Typically used through the Boxy::builder() factory method:

use boxy_cli::prelude::*;

let builder = Boxy::builder(); // Same as BoxyBuilder::new()

pub fn box_type(self, box_type: BoxType) -> Self

Sets the border type for the text box.

This determines the visual style of the box borders, including the characters used for corners, edges, and intersections. Different styles can create different visual effects, from simple ASCII-style boxes to double-lined or rounded boxes.

Arguments

• box_type - The border style from the BoxType enum

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

let builder = Boxy::builder()
    .box_type(BoxType::Double); // Use double-lined borders

// Or try other border styles
let rounded_box = Boxy::builder()
    .box_type(BoxType::Rounded)
    .build();

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

Sets the border color for the text box.

This method defines the color of the box borders, including corners, edges, and intersections. The color is specified using a hexadecimal color code (e.g. “#00ffff” for cyan).

Arguments

• box_color - A hex color code string (e.g. “#00ffff”, “#ff0000”)

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Create a box with cyan borders
let cyan_box = Boxy::builder()
    .color("#00ffff")
    .build();

// Create a box with red borders
let red_box = Boxy::builder()
    .color("#ff0000")
    .build();

Note

The actual appearance depends on terminal support for colors.

pub fn add_segment(self, text: &str, color: &str, text_align: BoxAlign) -> Self

Adds a new text segment to the box with specified text, color, and alignment.

Each segment represents a distinct section of the textbox that will be separated by horizontal dividers. This method is used to add the first or subsequent major sections of content.

Arguments

• text - The text content for this segment
• color - A hex color code (e.g. “#ffffff”) for the text color
• text_align - The alignment for this text segment (left, center, right)

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

let my_box = Boxy::builder()
    // Add a centered header segment in white
    .add_segment("Header", "#ffffff", BoxAlign::Center)
    // Add a left-aligned content segment in green
    .add_segment("Content goes here", "#00ff00", BoxAlign::Left)
    .build();

pub fn add_line(self, text: &str, color: &str) -> Self

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

This method adds a line of text to the last segment that was created. The new line will appear below the existing content in that segment. Unlike add_segment(), this does not create a new segment with a divider.

Arguments

• text - The text content to add as a new line
• color - A hex color code (e.g. “#ffffff”) for the text color

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

let my_box = Boxy::builder()
    // Add a header segment
    .add_segment("Header", "#ffffff", BoxAlign::Center)
    // Add a subheader as a new line in the same segment
    .add_line("Subheader text", "#aaaaaa")
    // Add a different segment with a divider
    .add_segment("Content section", "#00ff00", BoxAlign::Left)
    .build();

Panics

Panics if no segments have been added yet.

pub fn align(self, alignment: BoxAlign) -> Self

Sets the overall alignment of the text box within the terminal.

This method controls the horizontal positioning of the entire text box relative to the terminal width. It does not affect the alignment of text within the box segments, which is specified individually when adding segments.

Arguments

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

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Create a box centered in the terminal
let centered_box = Boxy::builder()
    .align(BoxAlign::Center)
    .add_segment("This box is centered in the terminal", "#ffffff", BoxAlign::Left)
    .build();

// Create a box aligned to the right edge of the terminal
let right_box = Boxy::builder()
    .align(BoxAlign::Right)
    .add_segment("This box is aligned to the right", "#ffffff", BoxAlign::Left)
    .build();

pub fn internal_padding(self, padding: BoxPad) -> Self

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

Internal padding creates space between the border of the box and the text inside it, providing visual breathing room for the content.

Arguments

• padding - A BoxPad instance specifying the internal padding values

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Set uniform internal padding of 2 spaces on all sides
let padded_box = Boxy::builder()
    .internal_padding(BoxPad::uniform(2))
    .build();

// Set different padding for each side (top, left, bottom, right)
let custom_pad_box = Boxy::builder()
    .internal_padding(BoxPad::from_tldr(1, 3, 1, 3))
    .build();

pub fn external_padding(self, padding: BoxPad) -> Self

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

External padding creates space between the edges of the terminal and the border of the box. This affects the positioning of the box within the terminal.

Arguments

• padding - A BoxPad instance specifying the external padding values

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Add 5 spaces of external padding on all sides
let padded_box = Boxy::builder()
    .external_padding(BoxPad::uniform(5))
    .build();

// Add 10 spaces of padding on the left side only
let left_padded_box = Boxy::builder()
    .external_padding(BoxPad::from_tldr(0, 10, 0, 0))
    .build();

pub fn padding(self, external: BoxPad, internal: BoxPad) -> Self

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

This is a convenience method that combines setting both external padding (between terminal edges and box) and internal padding (between box border and text) in one call.

Arguments

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

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Set both padding types at once
let box_with_padding = Boxy::builder()
    .padding(
        BoxPad::from_tldr(1, 5, 1, 5),  // external padding
        BoxPad::uniform(2)              // internal padding
    )
    .build();

pub fn width(self, width: usize) -> Self

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

By default, the text box automatically adjusts its width based on the terminal size. This method allows you to specify a fixed width instead, which can be useful for creating boxes of consistent size or for controlling the layout of multiple boxes.

Arguments

• width - The desired width in number of characters (including borders)

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Create a box with a fixed width of 50 characters
let fixed_width_box = Boxy::builder()
    .width(50)
    .add_segment("This box has a fixed width of 50 characters", "#ffffff", BoxAlign::Left)
    .build();

Note

Setting width to 0 returns to dynamic sizing based on terminal width.

pub fn height(self, height: usize) -> Self

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

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.

This method allows you to specify a fixed height for the box, which can be useful for creating boxes of consistent size or for controlling the layout of multiple boxes.

Arguments

• height - The desired height in number of lines (including borders)

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Create a box with a fixed height of 20 lines
let fixed_height_box = Boxy::builder()
    .height(20)
    .add_segment("This box has a fixed height", "#ffffff", BoxAlign::Center)
    .build();

pub fn segment_ratios(self, seg_index: usize, ratios: Vec<usize>) -> Self

Sets the size ratios between segments for vertical divisions.

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.

This method allows you to specify the relative width ratios when dividing a segment vertically into columns. Each number in the ratios vector represents the relative width of a column.

Arguments

• seg_index - The index of the segment to apply the ratios to
• ratios - A vector of relative width values for each column

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Create a box with a segment that has three columns in a 1:2:1 ratio
let columned_box = Boxy::builder()
    .add_segment("Segment with columns", "#ffffff", BoxAlign::Center)
    .segment_ratios(0, vec![1, 2, 1])
    .build();

pub fn set_terminal_width_offset(self, offset: i32) -> Self

Sets the offset used when calculating the dynamic width of the text box based on the terminal size.

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.

By default, when fixed_width is not set, the text box width is calculated as the terminal width minus 20 characters. This method allows you to customize this default offset to make the box wider or narrower relative to the terminal width.

Arguments

• offset - The number of characters to subtract from the terminal width. Positive values make the box narrower, negative values widen it.

Returns

The builder instance for method chaining

Examples

use boxy_cli::prelude::*;

// Make the box 10 characters narrower than the default
let narrower_box = Boxy::builder()
    .set_terminal_width_offset(30) // terminal width - 30
    .build();

// Make the box 10 characters wider than the default
let wider_box = Boxy::builder()
    .set_terminal_width_offset(10) // terminal width - 10
    .build();

Warning

Using negative offsets can cause the box to extend beyond the terminal boundaries, which may result in unexpected display issues.

pub fn build(self) -> Boxy<'a>

Builds the Boxy instance.

my_box.build();

Subsequently, display using display()

my_box.build().display();

Trait Implementations

impl<'a> Debug for BoxyBuilder<'a>

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

Formats the value using the given formatter.

impl<'a> Default for BoxyBuilder<'a>

fn default() -> BoxyBuilder<'a>

Returns the “default value” for a type.