Enum Role 

#[non_exhaustive]
pub enum Role<'a> {
    None,
    Unknown,
    Label(&'a str),
    AccessLabel(&'a str, Key),
    Button,
    CheckBox(bool),
    RadioButton(bool),
    Tab,
    TabPage,
    Border,
    ScrollRegion {
        offset: Offset,
        max_offset: Offset,
    },
    ScrollBar {
        direction: Direction,
        value: i32,
        max_value: i32,
    },
    Indicator,
    Image,
    Canvas,
    TextLabel {
        text: &'a str,
        cursor: usize,
        sel_index: usize,
    },
    TextInput {
        text: &'a str,
        multi_line: bool,
        cursor: usize,
        sel_index: usize,
    },
    Grip,
    Slider {
        min: f64,
        max: f64,
        step: f64,
        value: f64,
        direction: Direction,
    },
    SpinButton {
        min: f64,
        max: f64,
        step: f64,
        value: f64,
    },
    ProgressBar {
        fraction: f32,
        direction: Direction,
    },
    OptionList {
        len: Option<usize>,
        direction: Direction,
    },
    OptionListItem {
        index: Option<usize>,
        selected: Option<bool>,
    },
    Grid {
        columns: Option<usize>,
        rows: Option<usize>,
    },
    GridCell {
        info: Option<GridCellInfo>,
        selected: Option<bool>,
    },
    MenuBar,
    Menu {
        expanded: bool,
    },
    ComboBox {
        active: usize,
        text: &'a str,
        expanded: bool,
    },
    Splitter,
    Window,
    TitleBar,
}

Describes a widget’s purpose and capabilities

This enum does not describe children; use Tile::child_indices for that. This enum does not describe associated properties such as a label or labelled-by relationship.

Messages

Some roles of widget are expected to accept specific messages, as outlined below. See also EventState::send and related functions.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

None

The widget does not present any semantics under introspection

This is equivalent to the ARIA presentation role: the widget will be ignored by accessibility tools, while child widgets remain visible.

Unknown

Role is unspecified or no listed role is applicable

Unlike Role::None, the widget and its attached properties (e.g. label) will be visible to accessibility tools.

Label(&'a str)

A text label with the given contents, usually (but not necessarily) short and fixed

AccessLabel(&'a str, Key)

A text label with an access key

Button

A push button

Label

If no label is set explicitly then a label is inferred from children of the widget.

Messages

kas::messages::Activate may be used to trigger the button.

CheckBox(bool)

A checkable box

Label

If no label is set explicitly then a label is inferred from children of the widget.

Messages

kas::messages::Activate may be used to toggle the state.

RadioButton(bool)

A radio button

Label

If no label is set explicitly then a label is inferred from children of the widget.

Messages

kas::messages::Activate may be used to toggle the state.

Tab

A tab handle

Messages

kas::messages::Activate may be used to activate the tab.

TabPage

A stack / tab page

Border

A visible border surrounding or between other items

ScrollRegion

A scrollable region

The widget should support Event::Scroll.

Messages

kas::messages::SetScrollOffset may be used to set the scroll offset.

Fields

offset: Offset

The current scroll offset (from zero to max_offset)

max_offset: Offset

The maximum offset (non-negative)

ScrollBar

A scroll bar

Fields

direction: Direction

Orientation (usually either Down or Right)

value: i32

The current position (from zero to max_value)

max_value: i32

The maximum position (non-negative)

Indicator

A small visual element

Image

An image

Canvas

A canvas

TextLabel

A text label supporting selection

Fields

text: &'a str

Text contents

NOTE: it is likely that the representation here changes to accomodate more complex texts and potentially other details.

cursor: usize

The cursor index within contents

sel_index: usize

The selection index. Equals cursor if the selection is empty. May be less than or greater than cursor. (Aside: some toolkits call this the selection anchor but Kas does not; see kas::text::SelectionHelper.)

TextInput

Editable text

Messages

kas::messages::SetValueText may be used to replace the entire text. kas::messages::ReplaceSelectedText may be used to insert text at cursor, replacing all text between cursor and sel_index.

Fields

text: &'a str

Text contents

NOTE: it is likely that the representation here changes to accomodate more complex texts and potentially other details.

multi_line: bool

Whether the text input supports multi-line text

cursor: usize

The cursor index within contents

sel_index: usize

The selection index. Equals cursor if the selection is empty. May be less than or greater than cursor. (Aside: some toolkits call this the selection anchor but Kas does not; see kas::text::SelectionHelper.)

Grip

A gripable handle

This is a part of a slider, scroll-bar, splitter or similar widget which can be dragged by the mouse. Its Layout::rect may be queried.

Slider

A slider input

Note that values may not be finite; for example max: f64::INFINITY.

Messages

SetValueF64 may be used to set the input value.

IncrementStep and DecrementStep change the value by one step.

Fields

min: f64

Minimum value

max: f64

Maximum value

step: f64

Step

value: f64

Current value

direction: Direction

Orientation (direction of increasing values)

SpinButton

A spinner: numeric edit box with up and down buttons

Note that values may not be finite; for example max: f64::INFINITY.

Messages

SetValueF64 may be used to set the input value.

IncrementStep and DecrementStep change the value by one step.

Fields

min: f64

Minimum value

max: f64

Maximum value

step: f64

Step

value: f64

Current value

ProgressBar

A progress bar

Fields

fraction: f32

The reported value should be between 0.0 and 1.0.

direction: Direction

Orientation (direction of increasing values)

OptionList

A list of possibly selectable items

Note that this role should only be used where it is desirable to expose the list as an element. In other cases (where a list is used merely as a tool to place elements next to each other), use Role::None.

Child nodes should (but are not required to) use Role::OptionListItem.

Fields

len: Option<usize>

The number of items in the list, if known

direction: Direction

Orientation

OptionListItem

An item within a list

Fields

index: Option<usize>

Index in the list, if known

Note that this may change frequently, thus is not a useful key.

selected: Option<bool>

Whether the item is currently selected, if applicable.

When deciding whether to set this value to false or None, consider whether it would be appropriate for a screen reader to announce “not selected”.

See also accesskit::Node::is_selected.

Grid

A grid of possibly selectable items

Note that this role should only be used where it is desirable to expose the grid as an element. In other cases (where a grid is used merely as a tool to place elements next to each other), use Role::None.

Child nodes should (but are not required to) use Role::GridCell.

Fields

columns: Option<usize>

The number of columns in the grid, if known

rows: Option<usize>

The number of rows in the grid, if known

GridCell

An item within a list

Fields

info: Option<GridCellInfo>

Grid cell index and span, if known

selected: Option<bool>

Whether the item is currently selected, if applicable.

When deciding whether to set this value to false or None, consider whether it would be appropriate for a screen reader to announce “not selected”.

See also accesskit::Node::is_selected.

MenuBar

A menu bar

Menu

An openable menu

Messages

kas::messages::Activate may be used to open the menu.

kas::messages::Expand and kas::messages::Collapse may be used to open and close the menu.

Fields

expanded: bool

True if the menu is open

ComboBox

A drop-down combination box

Includes the index and text of the active entry

Messages

kas::messages::SetIndex may be used to set the selected entry.

kas::messages::Expand and kas::messages::Collapse may be used to open and close the menu.

Fields

active: usize

Index of the current choice

text: &'a str

Text of the current choice

expanded: bool

True if the menu is open

Splitter

A list of variable-size children with resizing grips

Window

A window

TitleBar

The special bar at the top of a window titling contents and usually embedding window controls