pub trait Layout {
// Required methods
fn rect(&self) -> Rect;
fn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules;
fn set_rect(&mut self, cx: &mut ConfigCx<'_>, rect: Rect, hints: AlignHints);
fn draw(&self, draw: DrawCx<'_>);
// Provided method
fn try_probe(&self, coord: Coord) -> Option<Id> { ... }
}Expand description
Positioning and drawing routines for Widgets
Layout is used to implement Widget sizing and drawing operations
(“layout”).
See Widget documentation and the #widget macro.
Layout may not be implemented independently.
§Implementation
The #widget macro will, when its layout property is specified,
generate an implementation of this trait (if omitted from the surrounding
#[impl_self]) or provide default implementations of its methods (if an
explicit impl of Layout is found but some methods are missing).
Required Methods§
Sourcefn rect(&self) -> Rect
fn rect(&self) -> Rect
Get the widget’s region
Coordinates are relative to the parent’s coordinate space.
This method is usually implemented by the #[widget] macro.
See also kas::widget_set_rect.
Sourcefn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules
fn size_rules(&mut self, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules
Get size rules for the given axis
§Calling
This method is called during sizing (see
widget lifecycle).
Typically, this method is called twice: first for the horizontal axis,
second for the vertical axis (with resolved width available through
the axis parameter allowing content wrapping).
For a description of the widget size model, see SizeRules.
§Call order
Required: self is configured (ConfigCx::configure) before this
method is called, and that size_rules is called for the
horizontal axis before it is called for the vertical axis.
Further, Self::set_rect must be called after this method before
drawing or event handling.
§Implementation
This method is expected to cache any size requirements calculated from
children which would be required for space allocations in
Self::set_rect. As an example, the horizontal SizeRules for a
row layout is the sum of the rules for each column (plus margins);
these per-column SizeRules are also needed to calculate column
widths in Self::size_rules once the available size is known.
For row/column/grid layouts, a crate::layout::RulesSolver engine
may be useful.
§Default implementation
The #[widget] macro may implement this method as a wrapper over
the corresponding MacroDefinedLayout.
Sourcefn set_rect(&mut self, cx: &mut ConfigCx<'_>, rect: Rect, hints: AlignHints)
fn set_rect(&mut self, cx: &mut ConfigCx<'_>, rect: Rect, hints: AlignHints)
Set size and position
§Calling
This method is called after Self::size_rules and may use values
cached by size_rules (in the case size_rules is not called first,
the widget may exhibit incorrect layout but should not panic). This
method should not write over values cached by size_rules since
set_rect may be called multiple times consecutively.
After set_rect is called, the widget must be ready for drawing and event handling.
§Call order
Required: Self::size_rules is called for both axes before this
method is called, and that this method has been called after the last
call to Self::size_rules before any of the following methods:
Layout::try_probe, Layout::draw, Events::handle_event.
§Implementation
The size of the assigned rect is normally at least the minimum size
requested by Self::size_rules, but this is not guaranteed. In case
this minimum is not met, it is permissible for the widget to draw
outside of its assigned rect and to not function as normal.
The assigned rect may be larger than the widget’s size requirements,
regardless of the Stretch policy used: containers divide up space
based on children’s SizeRules but do not attempt to align content
when excess space is available. Instead, content is responsible for
aligning itself using the provided hints and/or local information.
§Default implementation
The #[widget] macro may implement this method as a wrapper over
the corresponding MacroDefinedLayout.
Sourcefn draw(&self, draw: DrawCx<'_>)
fn draw(&self, draw: DrawCx<'_>)
Draw a widget and its children
§Calling
This method is invoked each frame to draw visible widgets. It should draw itself and recurse into all visible children.
§Call order
It is expected that Self::set_rect is called before this method,
but failure to do so should not cause a fatal error.
§Implementation
§Default implementation
The #[widget] macro may implement this method as a wrapper over
the corresponding MacroDefinedLayout.
§Method modification
The #[widget] macro injects a call to DrawCx::set_id into this
method where possible, allowing correct detection of disabled and
highlight states.
This method modification should never cause issues (besides the implied limitation that widgets cannot easily detect a parent’s state while being drawn).
Provided Methods§
Sourcefn try_probe(&self, coord: Coord) -> Option<Id>
fn try_probe(&self, coord: Coord) -> Option<Id>
Probe a coordinate for a widget’s Id
Returns the Id of the widget expected to handle clicks and touch
events at the given coord, or None if self does not occupy this
coord. Typically the result is the lowest descendant in
the widget tree at the given coord, but it is not required to be; e.g.
a Button may use an inner widget as a label but return its own Id
to indicate that the button (not the inner label) handles clicks.
§Calling
§Call order
It is expected that Layout::set_rect is called before this method,
but failure to do so should not cause a fatal error.
§Implementation
Widgets should implement Tile::probe instead, in which case an
implemention of this method will be provided:
self.rect().contains(coord).then(|| self.probe(coord))Derive-mode widgets may implement either method.
§Default implementation
Non-widgets do not have an Id, and therefore should use the default
implementation which simply returns None.
Implementations on Foreign Types§
Implementors§
impl Layout for Svg
impl Layout for TextEdit
impl Layout for AccessLabel
impl Layout for EventConfig
impl Layout for Filler
impl Layout for GripPart
This implementation is unusual (see GripPart documentation).
impl Layout for Image
impl Layout for Mark
impl Layout for Tab
impl Layout for TitleBar
impl Layout for TitleBarButtons
impl<A> Layout for MenuToggle<A>
impl<A> Layout for CheckBox<A>
impl<A> Layout for CheckButton<A>
impl<A> Layout for Page<A>
impl<A> Layout for RadioBox<A>
impl<A> Layout for RadioButton<A>
impl<A> Layout for Separator<A>
impl<A> Layout for Stack<A>
impl<A> Layout for TabStack<A>
impl<A, D> Layout for ProgressBar<A, D>where
D: Directional,
impl<A, T> Layout for ScrollText<A, T>where
T: FormattableText + 'static,
impl<A, T> Layout for SelectableText<A, T>where
T: FormattableText + 'static,
impl<A, T> Layout for SpinBox<A, T>where
T: SpinValue,
impl<A, T> Layout for kas::widgets::Text<A, T>where
T: Default + FormattableText + 'static,
impl<A, T, D> Layout for Slider<A, T, D>where
T: SliderValue,
D: Directional,
impl<A, V> Layout for ComboBox<A, V>
impl<A, W> Layout for MapAny<A, W>
impl<A, W> Layout for Adapt<A, W>where
W: Widget,
impl<A, W, F> Layout for Map<A, W, F>
impl<C> Layout for Float<C>where
C: Collection,
impl<C> Layout for Grid<C>where
C: CellCollection,
impl<C, D> Layout for List<C, D>where
C: Collection,
D: Directional,
impl<C, D> Layout for Splitter<C, D>where
C: Collection,
D: Directional,
impl<C, V> Layout for GridView<C, V>
impl<C, V, D> Layout for ListView<C, V, D>
impl<D> Layout for ScrollBar<D>where
D: Directional,
impl<Data> Layout for Window<Data>where
Data: AppData,
impl<Data, D> Layout for MenuBar<Data, D>where
D: Directional,
impl<F, A, V, G, D> Layout for FilterBoxListView<F, A, V, G, D>
impl<G> Layout for EditBox<G>where
G: EditGuard,
impl<G> Layout for EditField<G>where
G: EditGuard,
impl<M> Layout for MenuEntry<M>
impl<M> Layout for MarkButton<M>
impl<P> Layout for Canvas<P>where
P: CanvasProgram,
impl<T> Layout for kas::theme::Text<T>where
T: FormattableText,
Implement Layout, using default alignment where alignment is not provided