Struct List 

pub struct List<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: Collection, D> List<C, D>

where D: Default + Directional,

pub fn new(widgets: C) -> Self

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(cx, data, button);
                }
                Msg::Remove => {
                    let _ = row.pop(cx);
                }
            }
        }
    });

impl<C: Collection> List<C, Left>

pub fn left(widgets: C) -> Self

Construct a new instance with fixed direction

impl<C: Collection> List<C, Right>

pub fn right(widgets: C) -> Self

Construct a new instance with fixed direction

impl<C: Collection> List<C, Up>

pub fn up(widgets: C) -> Self

Construct a new instance with fixed direction

impl<C: Collection> List<C, Down>

pub fn down(widgets: C) -> Self

Construct a new instance with fixed direction

impl<C: Collection, D: Directional + Eq> List<C, D>

pub fn set_direction(&mut self, cx: &mut ConfigCx<'_>, direction: D)

Set the direction of contents

impl<C: Collection, D: Directional> List<C, D>

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

Construct a new instance with explicit direction

pub fn direction(&self) -> Direction

Get the direction of contents

pub fn with_direction(self, direction: D) -> Self

Set the direction of contents (inline)

pub fn layout_storage(&mut self) -> &mut (impl RowStorage + use<C, D>)

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: Widget, D: Directional> List<Vec<W>, D>

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

Remove all child widgets

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

Append a child widget

The new child is configured immediately. Triggers a resize.

Returns the new element’s index.

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

Remove the last child widget (if any) and return

Triggers a resize.

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

Inserts a child widget position index

Panics if index > len.

The new child is configured immediately. Triggers a resize.

pub fn remove(&mut self, cx: &mut ConfigCx<'_>, index: usize) -> W

Removes the child widget at position index

Panics if index is out of bounds.

Triggers a resize.

pub fn truncate(&mut self, cx: &mut ConfigCx<'_>, len: usize)

Removes all children at positions ≥ len

Does nothing if self.len() < len.

Triggers a resize.

pub fn replace( &mut self, cx: &mut ConfigCx<'_>, data: &W::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 a resize.

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

where T: IntoIterator<Item = W>,

Append child widgets from an iterator

New children are configured immediately. Triggers a resize.

pub fn resize_with<F>( &mut self, cx: &mut ConfigCx<'_>, data: &W::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 a 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: Default + Collection, D: Default + Directional,

fn default() -> Self

Returns the “default value” for a type.

impl<C: Collection, D: Directional> Events for List<C, D>

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

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

fn probe(&self, coord: Coord) -> Id

Probe a coordinate for a widget’s Id

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

Configure self

fn handle_event( &mut self, _: &mut EventCx<'_>, _: &Self::Data, _: Event<'_>, ) -> IsUsed

Handle an Event

const REDRAW_ON_MOUSE_OVER: bool = false

Does this widget have a different appearance on mouse over?

fn mouse_over_icon(&self) -> Option<CursorIcon>

The mouse pointer icon to use on mouse over

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

Configure self (post-child-configuration actions)

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

Update self using input data

fn recurse_indices(&self) -> ChildIndices

Recursion control

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

Mouse focus handler

fn child_nav_focus(&mut self, cx: &mut EventCx<'_>, id: Id)

Notification that a child received navigation focus

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

Handler for messages from children/descendants

fn handle_resize( &mut self, cx: &mut ConfigCx<'_>, data: &Self::Data, ) -> Option<ActionResize>

Handler for resize requests

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

Handler for scrolling

impl<W: Widget, D: Directional> Index<usize> for List<Vec<W>, D>

type Output = W

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<W: Widget, D: Directional> IndexMut<usize> for List<Vec<W>, D>

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

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

impl<C: Collection, D: Directional> Layout for List<C, D>

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

Calculate size requirements for an axis

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

Set size and position

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

Draw a widget and its children

fn rect(&self) -> Rect

Get the widget’s region

impl<C: Collection, D: Directional> Tile for List<C, D>

fn role(&self, _: &mut dyn RoleCx) -> Role<'_>

Describe the widget’s role

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

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

fn as_tile(&self) -> &dyn Tile

Get as a dyn Tile

fn id_ref(&self) -> &Id

Get a reference to the widget’s identifier

fn identify(&self) -> IdentifyWidget<'_>

Return a Display-able widget identifier

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

Access a child as a dyn Tile, if available

fn child_indices(&self) -> ChildIndices

Get child indices available to recursion

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

Probe a coordinate for a widget’s Id

fn nav_next(&self, reverse: bool, from: Option<usize>) -> Option<usize>

Navigation in spatial order

fn id(&self) -> Id

Get the widget’s identifier

fn navigable(&self) -> bool

Whether this widget supports navigation focus

fn tooltip(&self) -> Option<&str>

Tooltip

fn role_child_properties(&self, cx: &mut dyn RoleCx, index: usize)

Specify additional role properties for child index

fn translation(&self, index: usize) -> Offset

Get translation of child index relative to this widget

impl<C: Collection, D: Directional> Widget for List<C, D>

type Data = <C as Collection>::Data

Input data type

fn as_node<'__a>(&'__a mut self, data: &'__a Self::Data) -> Node<'__a>

Erase type

fn child_node<'__n>( &'__n mut self, data: &'__n Self::Data, index: usize, ) -> Option<Node<'__n>>

Access a child as a Node, if available