Widgets
The engine's headless UI widgets: buttons, checkboxes, radio groups, sliders, text inputs, menus, list boxes, tabs, trees, dialogs, popovers and scrollbars, and how their state works.
On this page
neo_ui_widgets provides the behaviour of common controls: what happens on click, drag and key press, keyboard focus and accessibility information. The widgets are headless: they have no look of their own. You build each one from ordinary nodes and style it with the components on Images and styling, so a widget can look like anything your game needs.
The widgets are on in NEO's builds, and DefaultPlugins registers all of them (UiWidgetsPlugins). Import them from neo::ui_widgets.
The widgets#
| Widget | Main components | Reports |
|---|---|---|
| Button | Button, optional ActivateOnPress | Activate |
| Checkbox or toggle | Checkbox, Checked (from neo::ui) | ValueChange<bool> |
| Radio group | RadioGroup with RadioButton children | ValueChange<Entity>: the chosen button |
| Slider | Slider, SliderValue, SliderRange, optional SliderStep and SliderPrecision; a child with SliderThumb | ValueChange<f32> |
| Text input | TextInput with EditableText; see UI text | Edits itself |
| Menu | MenuButton, MenuPopup, MenuItem | MenuEvent |
| List box | ListBox, ListItem, optional ListBoxMultiSelect | ValueChange<Entity>: the chosen row |
| Tabs | TabList with Tab children, SelectedTab | ValueChange<Option<Entity>>: the chosen tab |
| Tree view | TreeView, TreeItem | Selection and expand events |
| Dialog | Dialog, optional ModalDialog to trap focus, DialogDragHandle | RequestClose |
| Popover | Popover | Positions itself next to its parent, staying on screen |
| Scrollbar | Scrollbar, a child with ScrollbarThumb | Scrolls its target; see Scrolling and overflow |
Every widget is focusable and works with Tab and directional navigation. InteractionDisabled (from neo::ui) disables any of them.
How widget state works#
Most widgets don't change their own state. A checkbox doesn't tick itself when clicked: it reports a ValueChange<bool> with the proposed value, and your code decides what happens. That's because UI in games usually shows live game data. A volume slider should show the volume setting, and when the setting changes from somewhere else, the slider should follow.
So the pattern is:
- The widget's state lives in a component:
Checked,SliderValue,SelectedTab. - When the player interacts, the widget triggers
ValueChange<T>on itself, withvalueandis_final(false while a slider is still being dragged). - Your observer updates your game state and writes the new state component back to the widget.
use neo::{
prelude::*,
ui_widgets::{observe, Slider, SliderRange, SliderThumb, SliderValue, ValueChange},
};
#[derive(Resource)]
struct Volume(f32);
fn volume_slider(volume: f32) -> impl Bundle {
(
Node { width: px(200), height: px(12), ..default() },
Slider::default(),
SliderValue(volume),
SliderRange::new(0.0, 1.0),
observe(|change: On<ValueChange<f32>>, mut volume: ResMut<Volume>, mut commands: Commands| {
volume.0 = change.value;
commands.entity(change.source).insert(SliderValue(change.value));
}),
children![(
SliderThumb,
Node { position_type: PositionType::Absolute, width: px(12), height: px(12), ..default() },
BackgroundColor(Color::WHITE),
)],
)
}The slider doesn't move its thumb: a system of yours sets the thumb's left from SliderValue and SliderRange (filter on Changed<SliderValue>). The standard_widgets example has a complete slider, including how to account for the thumb's width.
If you don't need that control, add the matching self-update observer and the widget keeps its own state: checkbox_self_update, radio_self_update, slider_self_update, tablist_self_update and tree_view_self_update.
commands.spawn((
Checkbox,
Node { width: px(20), height: px(20), border: px(2).all(), ..default() },
BorderColor::all(Color::WHITE),
observe(checkbox_self_update),
));A few widgets work differently: buttons and menu items have no state and trigger Activate (or MenuEvent) instead; text inputs edit their own text, since it's large; and scrollbars write the target's ScrollPosition directly.
To set a value from code, insert the state component (SliderValue(0.5)), or trigger the widget's set event, such as SetSliderValue or SetChecked, which is handy for gamepad controls.
Style by state#
Read the state components in a system and pick a look, or observe their insertion and removal (On<Insert, Checked>, On<Remove, Checked>). Useful state components:
| Component | Meaning |
|---|---|
Hovered (neo::picking::hover) | The pointer is over it. Add Hovered::default() to track it. |
Pressed | It's held down. |
Checked | A checkbox, radio button or toggle is on. |
Selected, Expanded | List, tab and tree item state. |
InteractionDisabled | It's disabled. |
SliderDragState | A slider is being dragged. |
Writing your own widgets#
A widget is components plus observers. Follow the same conventions so yours mix with the built-in ones: keep state in a component, trigger ValueChange<T> instead of changing it, add Focusable, and stop the propagation of events your widget handles (event.propagate(false)) while letting others bubble.
Styled widgets#
The engine core also has neo_feathers, a styled widget set built on these widgets and used by several engine examples (feathers_gallery, feathers_counter). It needs the neo_feathers cargo feature, which isn't on in NEO's default builds.
Examples#
| Example | What it shows |
|---|---|
button | One styled button. |
standard_widgets | Button, slider, checkbox, radio group and menu, with state in a resource. |
standard_widgets_observers | The same, styled from observers. |
vertical_slider | Horizontal and vertical sliders that snap to steps. |
headless_tabs, headless_tree | Tabs and a tree view. |
scrollbars | Scrollbars on a scroll area. |
Run one from the engine core's workspace: cargo run --example standard_widgets.