Struct TuiGradientblock

pub struct TuiGradientblock { /* private fields */ }

A struct that represents a customizable block with gradient text, borders, and other visual elements.

This struct allows you to create and manage blocks that have a gradient color effect for text, customizable borders, and areas with specific alignments and fill styles.

Fields

• bordertype: Specifies the type of border style used for the block.
• fill: Defines the fill style for the block’s area (e.g., solid or gradient).
• top_titles: A vector of tuples where each tuple contains:
  • A String representing the title text.
  • A TitleAlignment indicating the alignment of the title.
  • An optional tuple of gradient colors (represented as a vector of (u8, u8, u8) tuples) and a factor that controls the spread of the gradient effect.
• bottom_titles: A similar vector to top_titles, but for titles placed at the bottom of the block.
• border_symbols: Defines the symbols used for the block’s borders.
• border_segments: Defines the segments of the block’s border.
• split_segments: Specifies how the block’s border is split into different sections.
• area: A Rect representing the block’s area, typically used for positioning and layout.

Example

let gradient_block = TuiGradientblock {
    bordertype: BorderStyle::Solid,
    fill: Fill::SolidColor((255, 0, 0)),
    top_titles: vec![("Top Title".to_owned(), TitleAlignment::Center, None)],
    bottom_titles: vec![("Bottom Title".to_owned(), TitleAlignment::Right, None)],
    border_symbols: BorderSymbols::Default,
    border_segments: BorderSegments::Full,
    split_segments: SplitBorderSegments::None,
    area: Rect::new(0, 0, 10, 5),
};

Implementations

impl TuiGradientblock

pub fn new(area: &Rect, split_segments: SplitBorderSegments) -> Self

pub fn interpolate_color( start: (u8, u8, u8), end: (u8, u8, u8), t: f32, factor: f32, ) -> (u8, u8, u8)

Interpolates between two colors based on a factor and a time value (t). This function computes a smooth transition between the start and end RGB colors using the given parameter t (which represents the position between the colors) and factor (which controls the curve of the interpolation).

Parameters

• start: A tuple representing the RGB values of the starting color (each value is a u8).
• end: A tuple representing the RGB values of the ending color (each value is a u8).
• t: A floating-point value (f32) between 0 and 1 that represents the interpolation factor, where t = 0 gives the start color, and t = 1 gives the end color.
• factor: A floating-point value (f32) that influences the smoothness or intensity of the interpolation. Higher values make the interpolation curve sharper, while lower values create a more gradual transition.

Returns

A tuple (u8, u8, u8) representing the interpolated RGB color, where each value is a byte (0-255).

Example

let start_color = (255, 0, 0); // Red
let end_color = (0, 0, 255); // Blue
let t = 0.5; // Midway between the colors
let factor = 1.0; // Linear interpolation
let result = interpolate_color(start_color, end_color, t, factor);

In this example, result will contain an RGB value that is a mix of red and blue, producing purple.

Note

• The interpolation is calculated using a smooth function based on t raised to the power of factor, which controls the rate of transition between the start and end colors.

pub fn create_gradient_text( text: &str, colors: Vec<(u8, u8, u8)>, factor: f32, ) -> Vec<Span<'static>>

Creates a gradient effect on a given text by interpolating between a list of colors based on the position of each character in the string.

Parameters

• text: A reference to the input String for which the gradient effect will be applied.
• colors: A vector of tuples representing the RGB values of the gradient colors. Each tuple contains three u8 values representing the Red, Green, and Blue components of a color.
• factor: A floating-point value (f32) that determines the intensity or spread of the gradient. Higher values will increase the spread of the gradient colors.

Returns

A Vec<Span<'static>> containing Span elements, where each Span represents a styled portion of the input text with the corresponding color from the gradient.

Panics

This function will panic if the number of colors in colors is less than 2. A gradient requires at least two colors to interpolate between. If fewer colors are provided, the following error message will be displayed:

╓───── IMPORTANT ─────╖
║                     ║
║ Use at least two    ║
║ colors.             ║
║                     ║
║ If you want to use  ║
║ a solid color,      ║
║ enter the same      ║
║ color more than once║
║                     ║
║ Example: Solid pink ║
║                     ║
║ ❌ [(250, 2, 238)]  ║
║ ✅ [                ║
║     (250, 2, 238),  ║
║     (250, 2, 238),  ║
║    ]                ║
║                     ║
╙─────────────────────╜

Example

let text = "Hello, World!".to_string();
let colors = vec![(255, 0, 0), (0, 255, 0), (0, 0, 255)];
let factor = 1.0;
let gradient_text = create_gradient_text(&text, colors, factor);

In the above example, the gradient_text will be a vector of Spans with the text “Hello, World!” styled with a gradient transitioning from red to green to blue.

Note

• The interpolate_color function is used internally to calculate the intermediate colors based on the position of the character relative to the total width of the text.

pub fn set_gradients( self, gradientlist: Vec<(GradientSegments, Vec<(u8, u8, u8)>, f32)>, ) -> Self

Sets gradient colors for specific segments of the border.

Parameters

• gradientlist: A vector of tuples where each tuple contains:
  • A GradientSegments enum value specifying which border segment to apply the gradient to.
  • A vector of RGB color tuples (Vec<(u8, u8, u8)>) representing the gradient colors.
  • A f32 value representing the gradient factor (e.g., intensity or blending weight).

Notes

• If a gradient should be a solid color, provide the same RGB value twice.
• Gradients must have at least two different colors to transition properly.

Example 1: Applying a gradient to the top border

let border = TuiGradientblock::new().set_gradients(vec![
    (GradientSegments::Top, vec![(255, 0, 0), (0, 0, 255)], 0.5),
]);

Example 2: Applying a solid color to the right border

let border = TuiGradientblock::new().set_gradients(vec![
    (GradientSegments::Right, vec![(50, 50, 50), (50, 50, 50)], 1.0),
]);

pub fn border_style(self, style: BorderStyle) -> Self

Sets the border style for the block.

If this function is not called, the border will be plain by default.

Parameters

• style: A BorderStyle enum value that determines the appearance of the border.
  • BorderStyle::Plain: A simple, unstyled border.
  • BorderStyle::Double: A double-lined border.
  • BorderStyle::Thick: A thick-stroked border.
  • BorderStyle::Rounded: A border with rounded corners.
  • BorderStyle::MiscBorder(MiscBorderTypes): A selection of miscellaneous predefined border styles.
  • BorderStyle::CustomBorderType: Allows custom border symbols to be set manually.

Example 1: Using a standard border style

let border = TuiGradientblock::new().border_style(BorderStyle::Double);

Example 2: Using a miscellaneous border style

let border = TuiGradientblock::new().border_style(BorderStyle::MiscBorder(MiscBorderTypes::Misc2));

Example 3: Using a custom border type

let border = TuiGradientblock::new()
    .border_style(BorderStyle::CustomBorderType)
    .top_left('╔')
    .top_right('╗')
    .bottom_left('╚')
    .bottom_right('╝');

Sets the border style of the block.

This function allows setting a predefined border style or a custom one.

Parameters

• style: A BorderStyle enum variant specifying the desired border style.

Behavior

• BorderStyle::CustomBorderType: Does not set predefined symbols, allowing manual customization.
• BorderStyle::MiscBorder(MiscBorderTypes): Uses a predefined miscellaneous border style.
• BorderStyle::Plain, BorderStyle::Double, BorderStyle::Thick, BorderStyle::Rounded: Sets the block’s borders to one of these predefined styles.

Example

let block = TuiGradientblock::new().border_style(BorderStyle::Double);

pub fn bottom_titles( self, titles: Vec<(String, TitleAlignment, Option<(Vec<(u8, u8, u8)>, f32)>)>, ) -> Self

Sets the titles that appear at the bottom of the border.

Parameters

• titles: A vector of tuples where each tuple contains:
  • A String representing the title text.
  • A TitleAlignment indicating how the title should be aligned (e.g., left, center, right).
  • An optional tuple containing a vector of RGB colors and a gradient factor (f32).

Example

let border = Border::new().bottom_titles(vec![
    ("Footer", TitleAlignment::Center, Some((vec![(255, 0, 0), (190, 3, 252)], 0.5))),
]);

pub fn top_titles( self, titles: Vec<(String, TitleAlignment, Option<(Vec<(u8, u8, u8)>, f32)>)>, ) -> Self

Sets the titles that appear at the top of the border.

Parameters

• titles: A vector of tuples where each tuple contains:
  • A String representing the title text.
  • A TitleAlignment indicating how the title should be aligned (e.g., left, center, right).
  • An optional tuple containing a vector of RGB colors and a gradient factor (f32).

Example 1: Without Gradient

let border = TuiGradientblock::new().top_titles(vec![
    ("Header", TitleAlignment::Left, None),
]);

Example 2: With Gradient

In this example, we use two different colors for the gradient (Red to Blue).

let border = TuiGradientblock::new().top_titles(vec![
    ("Header", TitleAlignment::Center, Some((vec![(255, 0, 0), (0, 0, 255)], 0.5))),
]);

pub fn top_right(self, symb: char) -> Self

Sets the symbol for the top-right corner of the border.

Parameters

• symb: A char representing the symbol to be used in the top-right corner.

Example

let border = TuiGradientblock::new().top_right('#');

pub fn top_left(self, symb: char) -> Self

Sets the symbol for the top-left corner of the border.

Parameters

• symb: A char representing the symbol to be used in the top-left corner.

Example

let border = TuiGradientblock::new().top_left('*');

pub fn bottom_right(self, symb: char) -> Self

Sets the symbol for the bottom-right corner of the border.

Parameters

• symb: A char representing the symbol to be used in the bottom-right corner.

Example

let border = TuiGradientblock::new().bottom_right('%');

pub fn bottom_left(self, symb: char) -> Self

Sets the symbol for the bottom-left corner of the border.

Parameters

• symb: A char representing the symbol to be used in the bottom-left corner.

Example

let border = TuiGradientblock::new().bottom_left('@');

pub fn bottom_horizontal_symbol(self, symb: char) -> Self

Sets the symbol for the bottom horizontal segment.

Parameters

• symb: A char representing the symbol to be used for the bottom horizontal border.

Example

let border = TuiGradientblockr::new().bottom_horizontal_symbol('-');

pub fn top_horizontal_symbol(self, symb: char) -> Self

Sets the symbol for the top horizontal border segment.

Parameters

• symb: A char representing the symbol to be used for the top horizontal border.

Example

let border = Border::new().top_horizontal_symbol('=');

pub fn right_vertical_symbol(self, symb: char) -> Self

Sets the symbol for the right vertical border segment.

Parameters

• symb: A char representing the symbol to be used for the right vertical border.

Example

let border = TuiGradientblock::new().right_vertical_symbol('|');

pub fn left_vertical_symbol(self, symb: char) -> Self

Sets the left vertical border symbol.

Example

let widget = TuiGradientblock::new().left_vertical_symbol('|');

pub fn top_center_symbol(self, symb: char) -> Self

Sets the top center border symbol.

Example

let widget = TuiGradientblock::new().top_center_symbol('─');

pub fn bottom_center_symbol(self, symb: char) -> Self

Sets the bottom center border symbol.

Example

let widget = TuiGradientblock::new().bottom_center_symbol('═');

pub fn left_center_symbol(self, symb: char) -> Self

Sets the left center vertical border symbol.

Example

let widget = TuiGradientblock::new().left_center_symbol('+');

pub fn right_center_symbol(self, symb: char) -> Self

Sets the right center vertical border symbol.

Example

let widget = TuiGradientblock::new().right_center_symbol('+');

pub fn top_horizontal_right_symbol(self, symb: char) -> Self

Sets the top right horizontal border symbol.

Example

let widget = TuiGradientblock::new().top_horizontal_right_symbol('┐');

pub fn bottom_horizontal_right_symbol(self, symb: char) -> Self

Sets the symbol used for the repeated section of the bottom horizontal border (right side).

Example

let block = TuiGradientblock::new().bottom_horizontal_right_symbol('*');

pub fn top_horizontal_left_symbol(self, symb: char) -> Self

Sets the symbol for the top horizontal left connector.

Example

let block = TuiGradientblock::new().top_horizontal_left_symbol('=');

pub fn bottom_horizontal_left_symbol(self, symb: char) -> Self

Sets the symbol for the bottom horizontal left connector.

Example

let block = TuiGradientblock::new().bottom_horizontal_left_symbol('=');

pub fn top_vertical_right_symbol(self, symb: char) -> Self

Sets the symbol for the top vertical right connector.

Example

let block = TuiGradientblock::new().top_vertical_right_symbol('|');

pub fn bottom_vertical_right_symbol(self, symb: char) -> Self

Sets the symbol for the bottom vertical right connector.

Example

let block = TuiGradientblock::new().bottom_vertical_right_symbol('|');

pub fn top_vertical_left_symbol(self, symb: char) -> Self

Sets the symbol for the top vertical left connector.

Example

let block = TuiGradientblock::new().top_vertical_left_symbol('|');

pub fn bottom_vertical_left_symbol(self, symb: char) -> Self

Sets the symbol for the bottom vertical left connector.

Example

let block = TuiGradientblock::new().bottom_vertical_left_symbol('|');

pub fn fill_string(self, string: String) -> Self

Sets the fill string for the block.

This string is used to fill the inner area of the block.

Example

let block = TuiGradientblock::new().fill_string(String::from("Hello"));

pub fn fill_gradient(self, colors: Vec<(u8, u8, u8)>, factor: f32) -> Self

Sets the fill gradient for the block.

The gradient is defined as a list of RGB colors and a factor to control the blending effect.

Example

let colors = vec![(255, 0, 0), (0, 255, 0), (0, 0, 255)];
let block = TuiGradientblock::new().fill_gradient(colors, 0.5);

pub fn set_lines(self) -> Self

Sets the border line segments based on the area and border symbols.

This method configures the border segments (top, bottom, left, right) and any possible splits within the block. It calculates and sets the text for each border line segment using the provided border symbols and the block’s area. The function supports setting up horizontal and vertical lines, as well as handling special cases where the border is split into smaller sections.

Important:

• This function should be called last after all other block properties are set, as it depends on the final values of the area and border symbols.

Behavior

• The function calculates the appropriate border segments, including top, bottom, left, and right borders.
• It uses the provided border_symbols to determine the characters used for the borders.
• If the split_segments attribute contains any of TOP, BOTTOM, LEFT, or RIGHT, the respective segments are split into smaller parts, and the relevant segments are marked for rendering.
• In the case of the ALL split, all border lines are broken into smaller segments and set to be rendered.
• If no split is needed (NONE), the function disables the rendering of split border lines.

Parameters

• This method takes no parameters and modifies the internal state of the struct it’s called on.

Returns

• A modified instance of the struct (self), with the border segments set according to the configurations.

pub fn main(&self, area: &Rect, buf: &mut Buffer)

Renders the TuiGradientblock widget, including optional fill and custom block rendering, along with top and bottom titles.

Parameters:

• area: A reference to a Rect that specifies the area to render the widget in.
• buf: A mutable reference to the Buffer where the rendered output will be stored.

This function:

• Checks if there is a fill string and calls render_fill if present.
• Renders the custom block using render_custom_block.
• Renders the top titles using render_top_titles.
• Renders the bottom titles using render_bottom_titles.

Trait Implementations

impl Clone for TuiGradientblock

fn clone(&self) -> TuiGradientblock

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Widget for TuiGradientblock

fn render(self, area: Rect, buf: &mut Buffer)

Renders the TuiGradientblock widget using the main function.

This is part of the Widget trait implementation. The render function takes an area and a mutable reference to the Buffer, and delegates rendering to the main function.

Parameters:

• area: A Rect that defines the area for rendering the widget.
• buf: A mutable reference to the Buffer where the rendered output will be stored.

Example:

let widget = TuiGradientblock::new();
let area = Rect::new(0, 0, 10, 10);
let mut buffer = Buffer::new();
widget.render(area, &mut buffer);