Struct kas_widgets::Grid

pub struct Grid<W: Widget> { /* private fields */ }

A generic grid widget

Child widgets are displayed in a grid, according to each child’s GridChildInfo. This allows spans and overlapping widgets. The numbers of rows and columns is determined automatically while the sizes of rows and columns are determined based on their contents (including special handling for spans, mostly with good results).

Note that all child widgets are stored in a list internally. The order of widgets in that list does not affect display position, but does have a few effects: (a) widgets may be accessed in this order via indexing, (b) widgets are configured and drawn in this order, (c) navigating through widgets with the Tab key currently uses the list order (though it may be changed in the future to use display order).

There is no protection against multiple widgets occupying the same cell. If this does happen, the last widget in that cell will appear on top, but overlapping widget drawing may not be pretty.

Alternatives

Where the entries are fixed, also consider custom Widget implementations.

Performance

Most operations are O(n) in the number of children.

Messages

If a handler is specified via Self::on_message then this handler is called when a child pushes a message.

Implementations

impl<W: Widget> Grid<W>

pub fn new() -> Self

Construct a new instance

pub fn new_vec(widgets: Vec<(GridChildInfo, W)>) -> Self

Construct a new instance

pub fn set_on_message(&mut self, f: Option<fn(_: &mut EventMgr<'_>, _: usize)>)

Assign a child message handler

This handler (if any) is called when a child pushes a message: f(mgr, index), where index is the child’s index.

pub fn on_message(self, f: fn(_: &mut EventMgr<'_>, _: usize)) -> Self

Assign a child message handler (inline style)

This handler is called when a child pushes a message: f(mgr, index), where index is the child’s index.

pub fn dimensions(&self) -> GridDimensions

Get grid dimensions

The numbers of rows, columns and spans is determined automatically.

pub fn layout_storage(&mut self) -> &mut impl GridStorage

Access layout storage

Use Self::dimensions to get expected dimensions.

pub fn build<F: FnOnce(GridBuilder<'_, W>)>(f: F) -> Self

Construct via a builder

pub fn edit<F: FnOnce(GridBuilder<'_, W>)>(&mut self, f: F) -> Action

Edit an existing grid via a builder

This may be used to edit children before window construction. It may also be used from a running UI, but in this case a full reconfigure of the window’s widgets is required (triggered by the the return value, Action::RECONFIGURE).

pub fn is_empty(&self) -> bool

True if there are no child widgets

pub fn len(&self) -> usize

Returns the number of child widgets

pub fn get(&self, index: usize) -> Option<&W>

Returns a reference to the child, if any

pub fn get_mut(&mut self, index: usize) -> Option<&mut W>

Returns a mutable reference to the child, if any

pub fn iter(&self) -> impl Iterator<Item = &(GridChildInfo, W)>

Iterate over childern

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut (GridChildInfo, W)>

Mutably iterate over childern

Trait Implementations

impl<W: Clone + Widget> Clone for Grid<W>

fn clone(&self) -> Grid<W>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<W: Widget> Debug for Grid<W>

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

Formats the value using the given formatter.

impl<W: Widget> Default for Grid<W>

fn default() -> Self

Returns the “default value” for a type.

impl<W: Widget> FromIterator<(GridChildInfo, W)> for Grid<W>

fn from_iter<T>(iter: T) -> Selfwhere T: IntoIterator<Item = (GridChildInfo, W)>,

Creates a value from an iterator.

impl<W: Widget> Index<usize> for Grid<W>

type Output = (GridChildInfo, W)

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<W: Widget> IndexMut<usize> for Grid<W>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<W: Widget> Layout for Grid<W>

fn size_rules(&mut self, mgr: SizeMgr<'_>, axis: AxisInfo) -> SizeRules

Get size rules for the given axis

fn set_rect(&mut self, mgr: &mut ConfigMgr<'_>, rect: Rect)

Set size and position

fn find_id(&mut self, coord: Coord) -> Option<WidgetId>

Translate a coordinate to a WidgetId

fn draw(&mut self, draw: DrawMgr<'_>)

Draw a widget and its children

impl<W: Widget> Widget for Grid<W>

fn handle_message(&mut self, mgr: &mut EventMgr<'_>)

Handler for messages from children/descendants

fn pre_configure(&mut self, _: &mut ConfigMgr<'_>, id: WidgetId)

Pre-configuration

fn configure(&mut self, mgr: &mut ConfigMgr<'_>)

Configure widget

fn navigable(&self) -> bool

Is this widget navigable via Tab key?

fn translation(&self) -> Offset

Get translation of children relative to this widget

fn nav_next( &mut self, mgr: &mut ConfigMgr<'_>, reverse: bool, from: Option<usize> ) -> Option<usize>

Navigation in spatial order

fn handle_event(&mut self, mgr: &mut EventMgr<'_>, event: Event) -> Response

Handle an Event sent to this widget

fn steal_event( &mut self, mgr: &mut EventMgr<'_>, id: &WidgetId, event: &Event ) -> Response

Potentially steal an event before it reaches a child

fn handle_unused(&mut self, mgr: &mut EventMgr<'_>, event: Event) -> Response

Handle an event sent to child index but left unhandled

fn handle_scroll(&mut self, mgr: &mut EventMgr<'_>, scroll: Scroll)

Handler for scrolling

impl<W: Widget> WidgetChildren for Grid<W>

fn num_children(&self) -> usize

Get the number of child widgets

fn get_child(&self, index: usize) -> Option<&dyn Widget>

Get a reference to a child widget by index, or None if the index is out of bounds.

fn get_child_mut(&mut self, index: usize) -> Option<&mut dyn Widget>

Mutable variant of get

fn find_child_index(&self, id: &WidgetId) -> Option<usize>

Find the child which is an ancestor of this id, if any

fn make_child_id(&mut self, index: usize) -> WidgetId

Make an identifier for a child

impl<W: Widget> WidgetCore for Grid<W>

fn id_ref(&self) -> &WidgetId

Get the widget’s identifier

fn rect(&self) -> Rect

Get the widget’s region, relative to its parent.

fn widget_name(&self) -> &'static str

Get the name of the widget struct

fn as_widget(&self) -> &dyn Widget

Erase type

fn as_widget_mut(&mut self) -> &mut dyn Widget

Erase type