Struct List

pub struct List<C, D>
where
    C: Collection,
    D: Directional,
{ /* private fields */ }

A generic row/column widget

A linear widget over a Collection of widgets.

When the collection uses Vec, various methods to insert/remove elements are available.

The layout direction D may be compile-time fixed (e.g. Right) or run-time mutable (Direction); in the latter case set_direction is available.

See also

Row and Column are type-defs to List which fix the direction D.

The macros row! and column! also create row/column layouts, but are not fully equivalent:

• row! and column! generate anonymous layout widgets (or objects). These do not have a set_direction method or support adding or removing elements.
• row! and column! generate layout objects which, when used within a custom widget, may refer to that widget’s fields.

Performance

Configuring and resizing elements is O(n) in the number of children. Drawing and event handling is O(log n) in the number of children (assuming only a small number are visible at any one time).

Example

use kas::collection;

let list = List::right(collection![
    "A checkbox",
    CheckBox::new(|_, state: &bool| *state),
]);

Implementations

impl<C, D> List<C, D>

where C: Collection, D: Directional + Default,

pub fn new(widgets: C) -> List<C, D>

Construct a new instance with default-constructed direction

This constructor is available where the direction is determined by the type: for D: Directional + Default. In other cases, use Self::new_dir.

Examples

Where widgets have the same type and the length is fixed, an array may be used:

use kas_widgets::{Label, Row};
let _ = Row::new([Label::new("left"), Label::new("right")]);

To support run-time insertion/deletion, use Vec:

use kas_widgets::{AdaptWidget, Button, Row};

#[derive(Clone, Debug)]
enum Msg {
    Add,
    Remove,
}

let _ = Row::new(vec![Button::label_msg("Add", Msg::Add)])
    .on_messages(|cx, row, data| {
        if let Some(msg) = cx.try_pop() {
            match msg {
                Msg::Add => {
                    let button = if row.len() % 2 == 0 {
                        Button::label_msg("Add", Msg::Add)
                    } else {
                        Button::label_msg("Remove", Msg::Remove)
                    };
                    row.push(&mut cx.config_cx(), data, button);
                }
                Msg::Remove => {
                    let _ = row.pop(&mut cx.config_cx());
                }
            }
        }
    });

impl<C> List<C, Left>

where C: Collection,

pub fn left(widgets: C) -> List<C, Left>

Construct a new instance with fixed direction

impl<C> List<C, Right>

where C: Collection,

pub fn right(widgets: C) -> List<C, Right>

Construct a new instance with fixed direction

impl<C> List<C, Up>

where C: Collection,

pub fn up(widgets: C) -> List<C, Up>

Construct a new instance with fixed direction

impl<C> List<C, Down>

where C: Collection,

pub fn down(widgets: C) -> List<C, Down>

Construct a new instance with fixed direction

impl<C> List<C, Direction>

where C: Collection,

pub fn set_direction(&mut self, direction: Direction) -> Action

Set the direction of contents

impl<C, D> List<C, D>

where C: Collection, D: Directional,

pub fn new_dir(widgets: C, direction: D) -> List<C, D>

Construct a new instance with explicit direction

pub fn direction(&self) -> Direction

Get the direction of contents

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

Access layout storage

The number of columns/rows is [Self.len].

pub fn is_empty(&self) -> bool

True if there are no child widgets

pub fn len(&self) -> usize

Returns the number of child widgets

impl<W, D> List<Vec<W>, D>

where W: Widget, D: Directional,

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 edit<F>(&mut self, f: F) -> Action

where F: FnOnce(&mut Vec<W>),

Edit the list of children directly

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 clear(&mut self)

Remove all child widgets

pub fn push( &mut self, cx: &mut ConfigCx<'_>, data: &<W as Widget>::Data, widget: W, ) -> usize

Append a child widget

The new child is configured immediately. Action::RESIZE is triggered.

Returns the new element’s index.

pub fn pop(&mut self, cx: &mut EventState) -> Option<W>

Remove the last child widget (if any) and return

Triggers Action::RESIZE.

pub fn insert( &mut self, cx: &mut ConfigCx<'_>, data: &<W as Widget>::Data, index: usize, widget: W, )

Inserts a child widget position index

Panics if index > len.

The new child is configured immediately. Triggers Action::RESIZE.

pub fn remove(&mut self, cx: &mut EventState, index: usize) -> W

Removes the child widget at position index

Panics if index is out of bounds.

Triggers Action::RESIZE.

pub fn replace( &mut self, cx: &mut ConfigCx<'_>, data: &<W as Widget>::Data, index: usize, w: W, ) -> W

Replace the child at index

Panics if index is out of bounds.

The new child is configured immediately. Triggers Action::RESIZE.

pub fn extend<T>( &mut self, cx: &mut ConfigCx<'_>, data: &<W as Widget>::Data, iter: T, )

where T: IntoIterator<Item = W>,

Append child widgets from an iterator

New children are configured immediately. Triggers Action::RESIZE.

pub fn resize_with<F>( &mut self, cx: &mut ConfigCx<'_>, data: &<W as Widget>::Data, len: usize, f: F, )

where F: Fn(usize) -> W,

Resize, using the given closure to construct new widgets

New children are configured immediately. Triggers Action::RESIZE.

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

Iterate over childern

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

Mutably iterate over childern

Trait Implementations

impl<C, D> Default for List<C, D>

where C: Collection + Default, D: Directional + Default,

fn default() -> List<C, D>

Returns the “default value” for a type.

impl<C, D> Events for List<C, D>

where C: Collection, D: Directional,

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

Make a fresh id based on self.next then insert into self.id_map

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

Configure self

fn handle_event( &mut self, _: &mut EventCx<'_>, _: &<List<C, D> as Widget>::Data, _: Event, ) -> IsUsed

Handle an Event

fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Configure children

fn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Update self using input data

fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Update children

fn navigable(&self) -> bool

Is this widget navigable via Tab key?

fn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool)

Mouse focus handler

fn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &Self::Data)

Handler for messages from children/descendants

fn handle_scroll( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, scroll: Scroll, )

Handler for scrolling

impl<W, D> Index<usize> for List<Vec<W>, D>

where W: Widget, D: Directional,

type Output = W

The returned type after indexing.

fn index(&self, index: usize) -> &<List<Vec<W>, D> as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl<W, D> IndexMut<usize> for List<Vec<W>, D>

where W: Widget, D: Directional,

fn index_mut( &mut self, index: usize, ) -> &mut <List<Vec<W>, D> as Index<usize>>::Output

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

impl<C, D> Layout for List<C, D>

where C: Collection, D: Directional,

fn num_children(&self) -> usize

Get the number of child widgets

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

Access a child as a dyn Layout

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

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

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

Get size rules for the given axis

fn set_rect(&mut self, cx: &mut ConfigCx<'_>, rect: Rect, hints: AlignHints)

Set size and position

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

Translate a coordinate to an Id

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

Draw a widget and its children

fn as_layout(&self) -> &dyn Layout

Get as a dyn Layout

fn id_ref(&self) -> &Id

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 nav_next(&self, reverse: bool, from: Option<usize>) -> Option<usize>

Navigation in spatial order

fn translation(&self) -> Offset

Get translation of children relative to this widget

impl<C, D> Widget for List<C, D>

where C: Collection, D: Directional,

type Data = <C as Collection>::Data

Input data type

fn for_child_node( &mut self, data: &<C as Collection>::Data, index: usize, closure: Box<dyn FnOnce(Node<'_>) + '_>, )

Call closure on child with given index, if index < self.num_children().

fn as_node<'a>(&'a mut self, data: &'a <List<C, D> as Widget>::Data) -> Node<'a>

Erase type