Struct 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 SizeCx or from a fixed quantity multiplied by SizeCx::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) -> Self

Construct for a fixed size

Margins are zero-sized by default; use Self::with_margin or Self::with_margins to set.

pub fn new(min: i32, ideal: i32, 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).

Margins are zero-sized by default; use Self::with_margin or Self::with_margins to set.

pub fn with_margin(self, margin: u16) -> Self

Set both margins (symmetric)

Both margins are set to the same value. By default these are 0.

pub fn with_margins(self, (first, second): (u16, u16)) -> Self

Set both margins (top/left, bottom/right)

By default these are 0.

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 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 solve_widths(widths: &mut [i32], rules: &[Self], target: i32)

Solve a sequence of rules with even distribution

Given a sequence of width (or height) rules from children and a target size, find an appropriate size for each child. The method attempts to ensure the following, in order of priority:

1. All widths are at least their minimum size requirement
2. The sum of widths plus margins between items equals target
3. No width exceeds its ideal size while other widths are below their own ideal size
4. No item with a Stretch priority less than the highest in rules exceeds its ideal size
5. When extra space is available and some widgets are below their ideal size, extra space is divided evenly between these widgets until they have reached their ideal size
6. If all rules use Stretch::None, then widths are not increased over their ideal size.
7. Extra space (after all widths are at least their ideal size) is shared equally between all widgets with the highest stretch priority

Input requirements: rules.len() == widths.len().

This method is idempotent: if input widths already match the above requirements then they will not be modified. Moreover, this method attempts to ensure that if target is increased, then decreased back to the previous value, this will revert to the previous solution. (The reverse may not hold if widths had previously been affected by a different agent.)

pub fn solve_widths_with_total( widths: &mut [i32], rules: &[Self], total: Self, target: i32, )

Solve a sequence of rules

This is the same as SizeRules::solve_widths except that the rules’ sum is passed explicitly.

Input requirements:

• rules.len() == widths.len()
• SizeRules::sum(rules) == total

pub fn solve_widths_with_priority( widths: &mut [i32], rules: &[Self], target: i32, last: bool, )

Solve a sequence of rules with priority distribution

Given a sequence of width (or height) rules from children and a target size, find an appropriate size for each child. The method attempts to ensure that:

1. All widths are at least their minimum size requirement
2. The sum of widths plus margins between items equals target
3. No width exceeds its ideal size while other widths are below their own ideal size
4. No item with a Stretch priority less than the highest in rules exceeds its ideal size
5. When extra space is available and some widgets are below their ideal size, extra space is divided evenly between these widgets until they have reached their ideal size
6. If all rules use Stretch::None, then widths are not increased over their ideal size.
7. Extra space (after all widths are at least their ideal size) is allocated to the first (or last) item with the highest stretch priority

Input requirements: rules.len() == widths.len().

This method is idempotent: given satisfactory input widths, these will be preserved. Moreover, this method attempts to ensure that if target is increased, then decreased back to the previous value, this will revert to the previous solution. (The reverse may not hold if widths had previously been affected by a different agent.)

Trait Implementations

impl Clone for SizeRules

fn clone(&self) -> SizeRules

Returns a duplicate 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 for SizeRules

fn eq(&self, other: &SizeRules) -> 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<'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

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum 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

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Copy for SizeRules

impl Eq for SizeRules

impl StructuralPartialEq for SizeRules