Skip to main content

Crate bevy_ui_widgets

Crate bevy_ui_widgets 

Source
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 Activate event 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.
ActivateOnPress
Optional marker component that indicates we want the button to activate on the pointer down event, this is used for menu buttons.
ActiveDescendant
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 Activate event when the button is un-pressed.
ButtonPlugin
Plugin that adds the observers for the Button widget.
Checkbox
Headless widget implementation for checkboxes. The Checked component represents the current state of the checkbox. The widget will emit a ValueChange<bool> event when clicked, or when the Enter or Space key is pressed while the checkbox is focused.
CheckboxPlugin
Plugin that adds the observers for the Checkbox widget.
Dialog
A dialog box. When ModalDialog is also present it traps focus and is backed by a crate::ModalDialogBarrier; when absent it is a movable, non-blocking floating window.
DialogDragHandle
Marks a region (e.g. a title bar) that drags its owning Dialog.
DialogDragState
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.
DialogPlugin
Plugin that adds the observers and systems for the Dialog widget.
DialogStack
Open floating dialogs, ordered bottom-to-top; the front-most is last.
ListBox
Headless widget implementation for a list box. This component contains multiple ListItem entities. It implements the tab navigation logic and keyboard shortcuts for list items.
ListBoxMultiSelect
Marker component that indicates we want to support multiple selection of list items.
ListBoxPlugin
Plugin that adds the observers for the ListBox widget.
ListItem
Headless widget implementation for listbox items. These should be enclosed within a ListBox widget, which is responsible for the mutual exclusion logic.
MenuButton
Headless menu button widget. This is meant to be combined with the Button component, and adds a few more key codes - arrow keys to open the popup.
MenuEvent
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.
MenuFocusSystem
System set for the system that menus use to acquire focus on one of its items upon first opening. It potentially modifies InputFocus.
MenuItem
Component that defines a menu item.
MenuPlugin
Plugin that adds the observers for the MenuItem component.
MenuPopup
Component that defines a popup menu container.
ModalDialog
Component that defines a modal dialog box.
ModalDialogBarrier
Component that defines the barrier element that covers the screen behind the dialog box.
ModalDialogPlugin
Plugin that adds the observers for the ModalDialog widget.
RadioButton
Headless widget implementation for radio buttons. They can be used independently, but enclosing them in a RadioGroup widget allows them to behave as a single, mutually exclusive unit.
RadioGroup
Headless widget implementation for a “radio button group”. This component is used to group multiple RadioButton components together, allowing them to behave as a single unit. It implements the tab navigation logic and keyboard shortcuts for radio buttons.
RadioGroupPlugin
Plugin that adds the observers for RadioButton and RadioGroup widget.
RequestClose
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.
ReselectListRow
Notification sent by a ListBox when the user commits the already-selected item, either by clicking it or by pressing Space/Enter while it is the active row. No ValueChange is emitted in this case, since the selection did not change. Used in for example a popup select control to close the popup when reselecting
ScrollArea
Marker component to enable trackpad / mouse wheel scrolling. This should be placed on an entity that has overflow: scroll.
ScrollAreaPlugin
Plugin that adds the observers for the ScrollArea widget.
ScrollIntoView
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.
ScrollbarDragState
Component used to manage the state of a scrollbar during dragging. This component is inserted on the thumb entity.
ScrollbarPlugin
Plugin that adds the observers for the Scrollbar widget.
ScrollbarTemplate
ScrollbarThumb
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.
SelectAllOnFocus
Marker component for EditableText widgets that should select all text on focus.
SelectedTab
The selected Tab within a TabList.
SelectedTabTemplate
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
SetSliderValue
An EntityEvent that can be triggered on a slider to modify its value (it will actually trigger a ValueChange event, hooking up a corresponding change to SliderValue is still the app’s responsibility, see slider_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 SliderValue component) and a range (represented by SliderRange). An optional step size can be specified via SliderStep, and you can control the rounding during dragging with SliderPrecision.
SliderDragState
Component used to manage the state of a slider during dragging.
SliderPlugin
Plugin that adds the observers for the Slider widget.
SliderPrecision
A component which controls the rounding of the slider value during dragging.
SliderRange
A component which represents the allowed range of the slider value. Defaults to 0.0..=1.0.
SliderStep
Defines the amount by which to increment or decrement the slider value when using keyboard shortcuts. Defaults to 1.0.
SliderThumb
Marker component that identifies which descendant element is the slider thumb.
SliderValue
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.
TextInput
Editable text widget.
TextInputPlugin
Enables support for the EditableText widget.
ToggleChecked
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.
UiWidgetsPlugins
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.
ValueChange
Notification sent by a widget that edits a scalar value.

Enums§

ControlOrientation
Used to select the orientation of a scrollbar, slider, or other oriented control.
ImeSystems
System sets for IME-related systems used by TextInputPlugin.
MenuAction
Action type for MenuEvent.
MenuFocusState
Component used to manage focus on the popup. Menu popups remain open only so long as they contain focus.
MenuLayout
Specifies the layout direction of the menu, for keyboard navigation
SliderOrientation
Controls the orientation of the slider.
SliderValueChange
The type of slider value change to apply in SetSliderValue.
TabActivation
Determines whether moving keyboard focus also requests tab selection.
TrackClick
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 ValueChange event. 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 ValueChange event. 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 ValueChange event. 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.