Enum Constraint

pub enum Constraint {
    Min(u16),
    Max(u16),
    Length(u16),
    Percentage(u16),
    Ratio(u32, u32),
    Fill(u16),
}

A constraint that defines the size of a layout element.

Constraints can be used to specify a fixed size, a percentage of the available space, a ratio of the available space, a minimum or maximum size or a fill proportional value for a layout element.

Relative constraints (percentage, ratio) are calculated relative to the entire space being divided, rather than the space available after applying more fixed constraints (min, max, length).

Constraints are prioritized in the following order:

1. Constraint::Min
2. Constraint::Max
3. Constraint::Length
4. Constraint::Percentage
5. Constraint::Ratio
6. Constraint::Fill

Examples

Constraint provides helper methods to create lists of constraints from various input formats.

use ratatui::layout::Constraint;

// Create a layout with specified lengths for each element
let constraints = Constraint::from_lengths([10, 20, 10]);

// Create a centered layout using ratio or percentage constraints
let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
let constraints = Constraint::from_percentages([25, 50, 25]);

// Create a centered layout with a minimum size constraint for specific elements
let constraints = Constraint::from_mins([0, 100, 0]);

// Create a sidebar layout specifying maximum sizes for the columns
let constraints = Constraint::from_maxes([30, 170]);

// Create a layout with fill proportional sizes for each element
let constraints = Constraint::from_fills([1, 2, 1]);

Variants

Min(u16)

Applies a minimum size constraint to the element

The element size is set to at least the specified amount.

Examples

[Percentage(100), Min(20)]

┌────────────────────────────┐┌──────────────────┐
│            30 px           ││       20 px      │
└────────────────────────────┘└──────────────────┘

[Percentage(100), Min(10)]

┌──────────────────────────────────────┐┌────────┐
│                 40 px                ││  10 px │
└──────────────────────────────────────┘└────────┘

Max(u16)

Applies a maximum size constraint to the element

The element size is set to at most the specified amount.

Examples

[Percentage(0), Max(20)]

┌────────────────────────────┐┌──────────────────┐
│            30 px           ││       20 px      │
└────────────────────────────┘└──────────────────┘

[Percentage(0), Max(10)]

┌──────────────────────────────────────┐┌────────┐
│                 40 px                ││  10 px │
└──────────────────────────────────────┘└────────┘

Length(u16)

Applies a length constraint to the element

The element size is set to the specified amount.

Examples

[Length(20), Length(20)]

┌──────────────────┐┌──────────────────┐
│       20 px      ││       20 px      │
└──────────────────┘└──────────────────┘

[Length(20), Length(30)]

┌──────────────────┐┌────────────────────────────┐
│       20 px      ││            30 px           │
└──────────────────┘└────────────────────────────┘

Percentage(u16)

Applies a percentage of the available space to the element

Converts the given percentage to a floating-point value and multiplies that with area. This value is rounded back to a integer as part of the layout split calculation.

Note: As this value only accepts a u16, certain percentages that cannot be represented exactly (e.g. 1/3) are not possible. You might want to use Constraint::Ratio or Constraint::Fill in such cases.

Examples

[Percentage(75), Fill(1)]

┌────────────────────────────────────┐┌──────────┐
│                38 px               ││   12 px  │
└────────────────────────────────────┘└──────────┘

[Percentage(50), Fill(1)]

┌───────────────────────┐┌───────────────────────┐
│         25 px         ││         25 px         │
└───────────────────────┘└───────────────────────┘

Ratio(u32, u32)

Applies a ratio of the available space to the element

Converts the given ratio to a floating-point value and multiplies that with area. This value is rounded back to a integer as part of the layout split calculation.

Examples

[Ratio(1, 2) ; 2]

┌───────────────────────┐┌───────────────────────┐
│         25 px         ││         25 px         │
└───────────────────────┘└───────────────────────┘

[Ratio(1, 4) ; 4]

┌───────────┐┌──────────┐┌───────────┐┌──────────┐
│   13 px   ││   12 px  ││   13 px   ││   12 px  │
└───────────┘└──────────┘└───────────┘└──────────┘

Fill(u16)

Applies the scaling factor proportional to all other Constraint::Fill elements to fill excess space

The element will only expand or fill into excess available space, proportionally matching other Constraint::Fill elements while satisfying all other constraints.

Examples

[Fill(1), Fill(2), Fill(3)]

┌──────┐┌───────────────┐┌───────────────────────┐
│ 8 px ││     17 px     ││         25 px         │
└──────┘└───────────────┘└───────────────────────┘

[Fill(1), Percentage(50), Fill(1)]

┌───────────┐┌───────────────────────┐┌──────────┐
│   13 px   ││         25 px         ││   12 px  │
└───────────┘└───────────────────────┘└──────────┘

Implementations

impl Constraint

pub const fn is_min(&self) -> bool

Returns true if the enum is Constraint::Min otherwise false

pub const fn is_max(&self) -> bool

Returns true if the enum is Constraint::Max otherwise false

pub const fn is_length(&self) -> bool

Returns true if the enum is Constraint::Length otherwise false

pub const fn is_percentage(&self) -> bool

Returns true if the enum is Constraint::Percentage otherwise false

pub const fn is_ratio(&self) -> bool

Returns true if the enum is Constraint::Ratio otherwise false

pub const fn is_fill(&self) -> bool

Returns true if the enum is Constraint::Fill otherwise false

impl Constraint

pub fn apply(&self, length: u16) -> u16

👎Deprecated since 0.26.0: This field will be hidden in the next minor version.

pub fn from_lengths<T>(lengths: T) -> Vec<Self>

where T: IntoIterator<Item = u16>,

Convert an iterator of lengths into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_lengths([1, 2, 3]);
let layout = Layout::default().constraints(constraints).split(area);

pub fn from_ratios<T>(ratios: T) -> Vec<Self>

where T: IntoIterator<Item = (u32, u32)>,

Convert an iterator of ratios into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]);
let layout = Layout::default().constraints(constraints).split(area);

pub fn from_percentages<T>(percentages: T) -> Vec<Self>

where T: IntoIterator<Item = u16>,

Convert an iterator of percentages into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_percentages([25, 50, 25]);
let layout = Layout::default().constraints(constraints).split(area);

pub fn from_maxes<T>(maxes: T) -> Vec<Self>

where T: IntoIterator<Item = u16>,

Convert an iterator of maxes into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_maxes([1, 2, 3]);
let layout = Layout::default().constraints(constraints).split(area);

pub fn from_mins<T>(mins: T) -> Vec<Self>

where T: IntoIterator<Item = u16>,

Convert an iterator of mins into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_mins([1, 2, 3]);
let layout = Layout::default().constraints(constraints).split(area);

pub fn from_fills<T>(proportional_factors: T) -> Vec<Self>

where T: IntoIterator<Item = u16>,

Convert an iterator of proportional factors into a vector of constraints

Examples

use ratatui::layout::{Constraint, Layout, Rect};

let constraints = Constraint::from_fills([1, 2, 3]);
let layout = Layout::default().constraints(constraints).split(area);

Trait Implementations

impl AsRef<Constraint> for Constraint

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Constraint

fn clone(&self) -> Constraint

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Constraint

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

Formats the value using the given formatter.

impl Default for Constraint

fn default() -> Self

Returns the “default value” for a type.

impl Display for Constraint

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

Formats the value using the given formatter.

impl From<&Constraint> for Constraint

fn from(constraint: &Self) -> Self

Converts to this type from the input type.

impl From<u16> for Constraint

fn from(length: u16) -> Self

Convert a u16 into a Constraint::Length

This is useful when you want to specify a fixed size for a layout, but don’t want to explicitly create a Constraint::Length yourself.

Examples

use ratatui::layout::{Constraint, Direction, Layout, Rect};

let layout = Layout::new(Direction::Vertical, [1, 2, 3]).split(area);
let layout = Layout::horizontal([1, 2, 3]).split(area);
let layout = Layout::vertical([1, 2, 3]).split(area);

impl Hash for Constraint

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Constraint

fn eq(&self, other: &Constraint) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Constraint

impl Eq for Constraint

impl StructuralPartialEq for Constraint