Expand description
This crate provides a set of standard widgets for Bevy UI, such as buttons, checkboxes, and sliders. These widgets have no inherent styling, it’s the responsibility of the user to add styling appropriate for their game or application.
§State Management
The typical way that UI widgets are used in games is that they often display a view of live data in the engine - they aren’t just passive form fields to fill in and then submit. For example, a “color picker” might have multiple ways to edit an RGB value, including sliders, a color plane, a color wheel, hex input, or swatches of recent colors. Interacting with any of these widgets not only updates the RGB model, but also updates all of the other widgets.
For this reason, almost all of the widgets use external state management: this means that the widgets do not automatically update their own internal state, but instead rely on the app to update the widget state (as well as any other related game state) in response to a change event emitted by the widget.
These widgets emit a ValueChange event which carries the proposed new state; the app should respond
to this event by updating its own internal model, and by updating the widget state. The general
convention is that the widget state is contained in a specific state-bearing component
(like SliderValue), and the widget detects when this component is inserted or replaced.
This design pattern draws from the classic “MVC” (Model / View / Controller) style of widget design, which is also used by React.js for controlled widgets.
There are a few exceptions to this rule:
- Buttons and menu items don’t have any state, so they emit an
Activateevent instead. (The hover and pressed states don’t count, because they are purely visual / stylistic). - Text input widgets have a large and expensive state, so they handle their own state updates.
- Scrollbars don’t emit events, they modify the scroll position of the target entity directly.
For users who don’t want to bother with writing a state update handler, these widgets provide
a “self update” observer function: for example, the checkbox_self_update observer will
listen for the ValueChange event and update the checkbox state. This effectively converts
it into an “uncontrolled” widget, in React.js terms.
§Best practices for event propagation
Generally, when a widget handles an event, propagation of that event to parent entities should be stopped. Events which are not of interest to the widget should be allowed to propagate. This “consume what you use” principle is important when writing your custom widgets, and understanding the behavior of existing widgets.
For more guidance on this, see the documentation for EntityEvent.
Modules§
- popover
- Framework for positioning of popups, tooltips, and other popover UI elements.
Structs§
- Activate
- Notification sent by a button or menu item.
- Activate
OnPress - Optional marker component that indicates we want the button to activate on the pointer down event, this is used for menu buttons.
- Active
Descendant - Component used for keyboard navigation. Individual rows should not be focusable in the normal way, as this would make tabbing through a long list tedious. Instead, we track the current “active” row separately using a component on the list box. The active row will be displayed with an outline.
- AddObserver
- Helper struct that adds an observer when inserted as a
Bundle. - Button
- Headless button widget. This widget maintains a “pressed” state, which is used to
indicate whether the button is currently being pressed by the user. It emits an
Activateevent when the button is un-pressed. - Button
Plugin - Plugin that adds the observers for the
Buttonwidget. - Checkbox
- Headless widget implementation for checkboxes. The
Checkedcomponent represents the current state of the checkbox. The widget will emit aValueChange<bool>event when clicked, or when theEnterorSpacekey is pressed while the checkbox is focused. - Checkbox
Plugin - Plugin that adds the observers for the
Checkboxwidget. - Dialog
- A dialog box. When
ModalDialogis also present it traps focus and is backed by acrate::ModalDialogBarrier; when absent it is a movable, non-blocking floating window. - Dialog
Drag Handle - Marks a region (e.g. a title bar) that drags its owning
Dialog. - Dialog
Drag State - Records the owning dialog’s translation when a drag begins, so each drag event can set an absolute position from the drag’s cumulative distance.
- Dialog
Plugin - Plugin that adds the observers and systems for the
Dialogwidget. - Dialog
Stack - Open floating dialogs, ordered bottom-to-top; the front-most is last.
- ListBox
- Headless widget implementation for a list box. This component contains multiple
ListItementities. It implements the tab navigation logic and keyboard shortcuts for list items. - List
BoxMulti Select - Marker component that indicates we want to support multiple selection of list items.
- List
BoxPlugin - Plugin that adds the observers for the
ListBoxwidget. - List
Item - Headless widget implementation for listbox items. These should be enclosed within a
ListBoxwidget, which is responsible for the mutual exclusion logic. - Menu
Button - Headless menu button widget. This is meant to be combined with the
Buttoncomponent, and adds a few more key codes - arrow keys to open the popup. - Menu
Event - Event used to control the state of the open menu. This bubbles upwards from the menu items and the menu container, through the portal relation, and to the menu owner entity.
- Menu
Focus System - System set for the system that menus use to acquire focus on one of its items upon first opening.
It potentially modifies
InputFocus. - Menu
Item - Component that defines a menu item.
- Menu
Plugin - Plugin that adds the observers for the
MenuItemcomponent. - Menu
Popup - Component that defines a popup menu container.
- Modal
Dialog - Component that defines a modal dialog box.
- Modal
Dialog Barrier - Component that defines the barrier element that covers the screen behind the dialog box.
- Modal
Dialog Plugin - Plugin that adds the observers for the
ModalDialogwidget. - Radio
Button - Headless widget implementation for radio buttons. They can be used independently,
but enclosing them in a
RadioGroupwidget allows them to behave as a single, mutually exclusive unit. - Radio
Group - Headless widget implementation for a “radio button group”. This component is used to group
multiple
RadioButtoncomponents together, allowing them to behave as a single unit. It implements the tab navigation logic and keyboard shortcuts for radio buttons. - Radio
Group Plugin - Plugin that adds the observers for
RadioButtonandRadioGroupwidget. - Request
Close - Event used to indicate that the dialog wants to be closed. This can happen because the user clicked on the barrier, hit the escape key, or clicked the close box in the dialog title. This event propagates so that the owner of the dialog can despawn it.
- Reselect
List Row - Notification sent by a
ListBoxwhen the user commits the already-selected item, either by clicking it or by pressing Space/Enter while it is the active row. NoValueChangeis emitted in this case, since the selection did not change. Used in for example a popup select control to close the popup when reselecting - Scroll
Area - Marker component to enable trackpad / mouse wheel scrolling. This should be placed on an entity that has overflow: scroll.
- Scroll
Area Plugin - Plugin that adds the observers for the
ScrollAreawidget. - Scroll
Into View - An event which indicates that we want to scroll the specified item into view (adjusting the scroll position of it’s parent).
- Scrollbar
- A headless scrollbar widget, which can be used to build custom scrollbars.
- Scrollbar
Drag State - Component used to manage the state of a scrollbar during dragging. This component is inserted on the thumb entity.
- Scrollbar
Plugin - Plugin that adds the observers for the
Scrollbarwidget. - Scrollbar
Template - Scrollbar
Thumb - This component indicates that the entity is a scrollbar thumb (the moving, draggable part of the scrollbar). This should be a child of the scrollbar entity.
- Select
AllOn Focus - Marker component for
EditableTextwidgets that should select all text on focus. - Selected
Tab - The selected
Tabwithin aTabList. - Selected
TabTemplate - SetChecked
- Event which can be triggered on a checkbox to set the checked state. This can be used to control the checkbox via gamepad buttons or other inputs.
- SetSelected
- Programmatically set which entity is selected (a single row of the list)
Wraps a call to send
ValueChange. No-op if already selected or disabled - SetSlider
Value - An
EntityEventthat can be triggered on a slider to modify its value (it will actually trigger aValueChangeevent, hooking up a corresponding change toSliderValueis still the app’s responsibility, seeslider_self_update). This can be used to control the slider via gamepad buttons or other inputs. The value will be clamped when the event is processed. - Slider
- A headless slider widget, which can be used to build custom sliders. Sliders have a value
(represented by the
SliderValuecomponent) and a range (represented bySliderRange). An optional step size can be specified viaSliderStep, and you can control the rounding during dragging withSliderPrecision. - Slider
Drag State - Component used to manage the state of a slider during dragging.
- Slider
Plugin - Plugin that adds the observers for the
Sliderwidget. - Slider
Precision - A component which controls the rounding of the slider value during dragging.
- Slider
Range - A component which represents the allowed range of the slider value. Defaults to 0.0..=1.0.
- Slider
Step - Defines the amount by which to increment or decrement the slider value when using keyboard shortcuts. Defaults to 1.0.
- Slider
Thumb - Marker component that identifies which descendant element is the slider thumb.
- Slider
Value - A component which stores the current value of the slider.
- Tab
- A headless tab header.
- TabList
- Headless tab-strip behavior and policy.
- TabPlugin
- Plugin that registers tab-list observers and derived state.
- Text
Input - Editable text widget.
- Text
Input Plugin - Enables support for the
EditableTextwidget. - Toggle
Checked - Event which can be triggered on a checkbox to toggle the checked state. This can be used to control the checkbox via gamepad buttons or other inputs.
- UiWidgets
Plugins - A plugin group that registers the observers for all of the widgets in this crate. If you don’t want to use all of the widgets, you can import the individual widget plugins instead.
- Value
Change - Notification sent by a widget that edits a scalar value.
Enums§
- Control
Orientation - Used to select the orientation of a scrollbar, slider, or other oriented control.
- ImeSystems
- System sets for IME-related systems used by
TextInputPlugin. - Menu
Action - Action type for
MenuEvent. - Menu
Focus State - Component used to manage focus on the popup. Menu popups remain open only so long as they contain focus.
- Menu
Layout - Specifies the layout direction of the menu, for keyboard navigation
- Slider
Orientation - Controls the orientation of the slider.
- Slider
Value Change - The type of slider value change to apply in
SetSliderValue. - TabActivation
- Determines whether moving keyboard focus also requests tab selection.
- Track
Click - Defines how the slider should behave when you click on the track (not the thumb).
Functions§
- checkbox_
self_ update - Observer function which updates the checkbox value in response to a
ValueChangeevent. This can be used to make the checkbox automatically update its own state when clicked, as opposed to managing the checkbox state externally. - listbox_
update_ selection - Observer function for updating list row selection state.
- observe
- Adds an observer as a bundle effect.
- radio_
self_ update - Observer function which updates the radio buttons in a group in response to a
ValueChangeevent. This can be used to make the radio buttons automatically update their own states and within the correct radio group when clicked, as opposed to managing the states externally. - slider_
self_ update - Observer function which updates the slider value in response to a
ValueChangeevent. This can be used to make the slider automatically update its own state when dragged, as opposed to managing the slider state externally. - tablist_
self_ update - Observer that applies tab selection requests to
SelectedTab.