pub struct SizeRules { /* private fields */ }
Expand description
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§
source§impl SizeRules
impl SizeRules
sourcepub const EMPTY: 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
.
sourcepub const fn empty(stretch: Stretch) -> SizeRules
pub const fn empty(stretch: Stretch) -> SizeRules
Empty space with the given stretch priority
See warning on SizeRules::EMPTY
.
sourcepub fn fixed(size: i32, margins: (u16, u16)) -> SizeRules
pub fn fixed(size: i32, margins: (u16, u16)) -> SizeRules
A fixed size with given (pre, post)
margins
sourcepub fn fixed_splat(size: i32, margin: u16) -> SizeRules
pub fn fixed_splat(size: i32, margin: u16) -> SizeRules
A fixed size with given (symmetric) margin
sourcepub fn fixed_scaled(size: f32, margins: f32, scale_factor: f32) -> SizeRules
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.
sourcepub fn extract<D>(
dir: D,
size: Size,
margins: Margins,
stretch: Stretch
) -> SizeRuleswhere
D: Directional,
pub fn extract<D>(
dir: D,
size: Size,
margins: Margins,
stretch: Stretch
) -> SizeRuleswhere
D: Directional,
Construct rules from given data
sourcepub fn extract_fixed<D>(dir: D, size: Size, margin: Margins) -> SizeRuleswhere
D: Directional,
pub fn extract_fixed<D>(dir: D, size: Size, margin: Margins) -> SizeRuleswhere
D: Directional,
Construct fixed-size rules from given data
sourcepub fn new(
min: i32,
ideal: i32,
margins: (u16, u16),
stretch: Stretch
) -> SizeRules
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).
sourcepub fn with_stretch(self, stretch: Stretch) -> SizeRules
pub fn with_stretch(self, stretch: Stretch) -> SizeRules
Set stretch factor, inline
sourcepub fn ideal_size(self) -> i32
pub fn ideal_size(self) -> i32
Get the ideal size
sourcepub fn margins_i32(self) -> (i32, i32)
pub fn margins_i32(self) -> (i32, i32)
Get the (pre, post)
margin sizes, cast to i32
sourcepub fn set_stretch(&mut self, stretch: Stretch)
pub fn set_stretch(&mut self, stretch: Stretch)
Set the stretch priority
sourcepub fn set_margins(&mut self, margins: (u16, u16))
pub fn set_margins(&mut self, margins: (u16, u16))
Set margins
sourcepub fn include_margins(&mut self, margins: (u16, u16))
pub fn include_margins(&mut self, margins: (u16, u16))
Set margins to max of own margins and given margins
sourcepub fn multiply_with_margin(&mut self, min_factor: i32, ideal_factor: i32)
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.
sourcepub fn append(&mut self, rhs: SizeRules)
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.
sourcepub fn appended(self, rhs: SizeRules) -> SizeRules
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.
sourcepub fn min_sum(range: &[SizeRules]) -> SizeRules
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
sourcepub fn sub_add(&mut self, x: SizeRules, y: SizeRules)
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
.
sourcepub fn reduce_min_to(&mut self, min: i32)
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.
sourcepub fn distribute_span_over(self, rules: &mut [SizeRules])
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§
source§impl PartialEq for SizeRules
impl PartialEq for SizeRules
source§impl<'a> Sum<&'a SizeRules> 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.
source§impl Sum for SizeRules
impl Sum for SizeRules
Return the sum over a sequence of rules, assuming these are ordered
Uses SizeRules::appended
on all rules in sequence.
impl Copy for SizeRules
impl Eq for SizeRules
impl StructuralEq for SizeRules
impl StructuralPartialEq for SizeRules
Auto Trait Implementations§
impl RefUnwindSafe for SizeRules
impl Send for SizeRules
impl Sync for SizeRules
impl Unpin for SizeRules
impl UnwindSafe for SizeRules
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<S, T> CastApprox<T> for Swhere
T: ConvApprox<S>,
impl<S, T> CastApprox<T> for Swhere
T: ConvApprox<S>,
§fn try_cast_approx(self) -> Result<T, Error>
fn try_cast_approx(self) -> Result<T, Error>
§fn cast_approx(self) -> T
fn cast_approx(self) -> T
§impl<S, T> CastFloat<T> for Swhere
T: ConvFloat<S>,
impl<S, T> CastFloat<T> for Swhere
T: ConvFloat<S>,
§fn cast_trunc(self) -> T
fn cast_trunc(self) -> T
§fn cast_nearest(self) -> T
fn cast_nearest(self) -> T
§fn cast_floor(self) -> T
fn cast_floor(self) -> T
§fn try_cast_trunc(self) -> Result<T, Error>
fn try_cast_trunc(self) -> Result<T, Error>
§fn try_cast_nearest(self) -> Result<T, Error>
fn try_cast_nearest(self) -> Result<T, Error>
§fn try_cast_floor(self) -> Result<T, Error>
fn try_cast_floor(self) -> Result<T, Error>
§fn try_cast_ceil(self) -> Result<T, Error>
fn try_cast_ceil(self) -> Result<T, Error>
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.§impl<T> DowncastSync for T
impl<T> DowncastSync for T
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
§impl<T> Pointable for T
impl<T> Pointable for T
source§impl<R, P> ReadPrimitive<R> for P
impl<R, P> ReadPrimitive<R> for P
source§fn read_from_little_endian(read: &mut R) -> Result<Self, Error>
fn read_from_little_endian(read: &mut R) -> Result<Self, Error>
ReadEndian::read_from_little_endian()
.