Struct kas::layout::SizeRules

pub struct SizeRules { /* fields omitted */ }

Widget sizing information

This is the return value of kas::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 StretchPolicy

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 StretchPolicy being prioritised extra space. Usually rows/columns will be stretched to use all available space, the exception being when none have a policy higher than StretchPolicy::Fixed. When expanding a row/column, the highest stretch policy 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 SizeRules::surrounded_by. 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 kas::Layout::set_rect for more information.

For widgets with a stretch policy of StretchPolicy::Fixed, 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 kas::Layout::set_rect and kas::AlignHints.

Methods

impl SizeRules

pub const EMPTY: Self

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: StretchPolicy) -> Self

Empty space with the given stretch policy

See warning on SizeRules::EMPTY.

pub fn fixed(size: u32, margins: (u16, u16)) -> Self

A fixed size with given (pre, post) margins

pub fn extract_fixed(vertical: bool, size: Size, margin: Margins) -> Self

Construct fixed-size rules from given data

pub fn new(
    min: u32,
    ideal: u32,
    margins: (u16, u16),
    stretch: StretchPolicy
) -> Self

Construct with custom rules

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

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

pub fn min_size(self) -> u32

Get the minimum size

pub fn ideal_size(self) -> u32

Get the ideal size

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

Get the (pre, post) margin sizes

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

Set margins to max of own margins and given margins

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

Use the maximum size of self and rhs.

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

Set self = self.max(rhs);

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) -> Self

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 surrounded_by(self, frame: SizeRules, internal_margins: bool) -> Self

Return the rules for self surrounded by frame

If internal_margins are true, then space is allocated for self's margins inside the frame; if not, then self's margins are merged with the frame's margins.

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: Self, y: Self)

Set self to self - x + y

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

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 [Self])

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

fn clone(&self) -> SizeRules

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for SizeRules

impl Debug for SizeRules

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

Formats the value using the given formatter.

impl Default for SizeRules

fn default() -> SizeRules

Returns the "default value" for a type.

impl Eq for SizeRules

impl PartialEq<SizeRules> for SizeRules

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

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

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

This method tests for !=.

impl StructuralEq for SizeRules

impl StructuralPartialEq for SizeRules

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.

fn sum<I: Iterator<Item = &'a Self>>(iter: I) -> Self

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.

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

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