Struct kas::layout::SizeRules

pub struct SizeRules { /* fields omitted */ }

Widget sizing information

This is the return value of crate::Layout::size_rules and is used to describe size and margin requirements for widgets. This type only concerns size requirements along a single axis.

All units are in pixels. Sizes usually come directly from SizeHandle or from a fixed quantity multiplied by SizeHandle::scale_factor.

Sizes

The widget size model is simple: a rectangular box, plus a margin on each side. Widget sizes are calculated from available space and the SizeRules; these rules currently include:

• the minimum size required for correct operation
• the preferred / ideal size
• a Stretch priority

Available space is distributed between widgets depending on whether the space is below the minimum, between the minimum and preferred, or above the preferred size, with widgets with the highest Stretch priority being prioritised extra space. Usually rows/columns will be stretched to use all available space, the exception being when none have a priority higher than Stretch::None. When expanding a row/column, the highest stretch priority of all contents will be used.

Margins

Required margin sizes are handled separately for each side of a widget. Since SizeRules concerns only one axis, it stores only two margin sizes: “pre” (left/top) and “post” (right/bottom). These are stored as u16 values on the assumption that no margin need exceed 65536.

When widgets are placed next to each other, their margins may be combined; e.g. if a widget with margin of 6px is followed by another with margin 2px, the required margin between the two is the maximum, 6px.

Only the layout engine and parent widgets need consider margins (beyond their specification). For these cases, one needs to be aware that due to margin-merging behaviour, one cannot simply “add” two SizeRules. Instead, when placing one widget next to another, use SizeRules::append or SizeRules::appended; when placing a widget within a frame, use FrameRules::surround_with_margin or FrameRules::surround_as_margin. When calculating the size of a sequence of widgets, one may use the Sum implementation (this assumes that the sequence is in left-to-right or top-to-bottom order).

Alignment

SizeRules concerns calculations of size requirements, which the layout engine uses to assign each widget a Rect; it is up to the widget itself to either fill this rect or align itself within the given space. See crate::Layout::set_rect for more information.

For widgets with a stretch priority of Stretch::None, it is still possible for layout code to assign a size larger than the preference. It is up to the widget to align itself within this space: see crate::Layout::set_rect and crate::layout::AlignHints.

Implementations

impl SizeRules

pub const EMPTY: SizeRules

Empty (zero size) widget

Warning: appending another size to EMPTY does include margins even though EMPTY itself has zero size. However, EMPTY itself has zero-size margins, so this only affects appending an EMPTY with a non-empty SizeRules.

pub const fn empty(stretch: Stretch) -> SizeRules

Empty space with the given stretch priority

See warning on SizeRules::EMPTY.

pub fn fixed(size: i32, margins: (u16, u16)) -> SizeRules

A fixed size with given (pre, post) margins

pub fn fixed_scaled(size: f32, margins: f32, scale_factor: f32) -> SizeRules

A fixed size, scaled from virtual pixels

This is a shortcut to SizeRules::fixed using virtual-pixel sizes and a scale factor. It also assumes both margins are equal.

pub fn extract<D>(
    dir: D,
    size: Size,
    margins: Margins,
    stretch: Stretch
) -> SizeRules where
    D: Directional, 

Construct rules from given data

pub fn extract_fixed<D>(dir: D, size: Size, margin: Margins) -> SizeRules where
    D: Directional, 

Construct fixed-size rules from given data

pub fn new(
    min: i32,
    ideal: i32,
    margins: (u16, u16),
    stretch: Stretch
) -> SizeRules

Construct with custom rules

Region size should meet the given min-imum size and has a given ideal size, plus a given stretch priority.

Expected: ideal >= min (if not, ideal is clamped to min).

pub fn new_scaled(
    min: f32,
    ideal: f32,
    margins: f32,
    stretch: Stretch,
    scale_factor: f32
) -> SizeRules

Construct with custom rules, scaled from virtual pixels

This is a shortcut around SizeRules::new. It assumes that both margins are equal.

Region size should meet the given min-imum size and has a given ideal size, plus a given stretch priority.

Expected: ideal >= min (if not, ideal is clamped to min).

pub fn min_size(self) -> i32

Get the minimum size

pub fn ideal_size(self) -> i32

Get the ideal size

pub fn max_size(self) -> i32

Get the max size

With most stretch policies, this returns i32::MAX, but with Stretch::None, this is SizeRules::ideal_size.

pub fn margins(self) -> (u16, u16)

Get the (pre, post) margin sizes

pub fn margins_i32(self) -> (i32, i32)

Get the (pre, post) margin sizes, cast to i32

pub fn stretch(self) -> Stretch

Get the stretch priority

pub fn set_stretch(&mut self, stretch: Stretch)

Set the stretch priority

pub fn include_margins(&mut self, margins: (u16, u16))

Set margins to max of own margins and given margins

pub fn max(self, rhs: SizeRules) -> SizeRules

Use the maximum size of self and rhs.

pub fn max_with(&mut self, rhs: SizeRules)

Set self = self.max(rhs);

pub fn multiply_with_margin(&mut self, min_factor: i32, ideal_factor: i32)

Multiply the (min, ideal) size, including internal margins

E.g. given margin = margins.0 + margins.1 and factors (2, 5), the minimum size is set to min * 2 + margin and the ideal to ideal * 5 + 4 * margin.

Panics if either factor is 0.

pub fn append(&mut self, rhs: SizeRules)

Append the rules for rhs to self

This implies that rhs rules concern an element to the right of or below self. Note that order matters since margins may be combined.

Note also that appending SizeRules::EMPTY does include interior margins (those between EMPTY and the other rules) within the result.

pub fn appended(self, rhs: SizeRules) -> SizeRules

Return the rules for self appended by rhs

This implies that rhs rules concern an element to the right of or below self. Note that order matters since margins may be combined.

Note also that appending SizeRules::EMPTY does include interior margins (those between EMPTY and the other rules) within the result.

pub fn sum(range: &[SizeRules]) -> SizeRules

Return the result of appending all given ranges

pub fn min_sum(range: &[SizeRules]) -> SizeRules

Return the result of appending all given ranges (min only)

This is a specialised version of sum: only the minimum is calculated

pub fn sub_add(&mut self, x: SizeRules, y: SizeRules)

Set self to self - x + y, clamped to 0 or greater

This is a specialised operation to join two spans, subtracing the common overlap (x), thus margins are self.m.0 and y.m.1.

pub fn reduce_min_to(&mut self, min: i32)

Reduce the minimum size

If min is greater than the current minimum size, this has no effect.

pub fn distribute_span_over(self, rules: &mut [SizeRules])

Adjust a sequence of rules to ensure that the total is at least self

This is used by grids to ensure that cell spans are sufficiently large.

Trait Implementations

impl Clone for SizeRules

pub fn clone(&self) -> SizeRules

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SizeRules

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

Formats the value using the given formatter.

impl Default for SizeRules

pub fn default() -> SizeRules

Returns the “default value” for a type.

impl PartialEq<SizeRules> for SizeRules

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a> Sum<&'a SizeRules> for SizeRules

Return the sum over a sequence of rules, assuming these are ordered

Uses SizeRules::appended on all rules in sequence.

pub fn sum<I>(iter: I) -> SizeRules where
    I: Iterator<Item = &'a SizeRules>, 

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum<SizeRules> for SizeRules

Return the sum over a sequence of rules, assuming these are ordered

Uses SizeRules::appended on all rules in sequence.

pub fn sum<I>(iter: I) -> SizeRules where
    I: Iterator<Item = SizeRules>, 

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl Copy for SizeRules

impl Eq for SizeRules

impl StructuralEq for SizeRules

impl StructuralPartialEq for SizeRules