Struct kas_core::layout::SizeRules

pub struct SizeRules { /* private fields */ }

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 SizeMgr or from a fixed quantity multiplied by SizeMgr::scale_factor.

Sizes

The widget size model is simple: a rectangular box, plus a margin on each side. The SizeRules type represents expectations along a single axis:

• The minimum acceptable size (almost always met)
• The ideal size (often the same size; this distinction is most useful for scrollable regions which are ideally large enough not to require scrolling, but can be much smaller)
• A Stretch priority, used to prioritize allocation of excess space

Note that Stretch::None does not prevent stretching, but simply states that it is undesired (lowest priority). Actually preventing stretching requires alignment.

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. 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: 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: Stretch) -> Self

Empty space with the given stretch priority

See warning on SizeRules::EMPTY.

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

A fixed size with given (pre, post) margins

pub fn fixed_splat(size: i32, margin: u16) -> Self

A fixed size with given (symmetric) margin

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

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: Directional>(
    dir: D,
    size: Size,
    margins: Margins,
    stretch: Stretch
) -> Self

Construct rules from given data

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

Construct fixed-size rules from given data

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

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 with_stretch(self, stretch: Stretch) -> Self

Set stretch factor, inline

pub fn min_size(self) -> i32

Get the minimum size

pub fn ideal_size(self) -> i32

Get the 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 set_margins(&mut self, margins: (u16, u16))

Set margins

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 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) -> 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 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, 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 [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 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 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: &Rhs) -> bool

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

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.

impl Copy for SizeRules

impl Eq for SizeRules

impl StructuralEq for SizeRules

impl StructuralPartialEq for SizeRules