A widget library built on top of bevy's internal bevy_ui.

If you clone the repository, you can simply build and run the main example:

cargo build
cargo run --example simple_editor

Main missing features:

• Centralized focus management
• Text / Text area input widgets

What it can already do:

• Resizable layout
  • Rows / columns
  • Scroll views
  • Docking zones
  • Tab containers
  • Floating panels
  • Sized zones
  • Foldables
• Input
  • Slider
  • Dropdown
  • Checkbox
  • Radio groups
• Menu
  • Menu item (with leading/trailing icons and support for keyboard shortcuts)
  • Toggle menu item
  • Submenu
  • Context menu (component-based)
• Static
  • Icon
  • Label
• Utility
  • Command-based styling
  • Temporal tracking of interactions
  • Animated interactions
  • Context based extensions
  • Drag / drop interactions
  • Scroll interactions
• Theming
  • Material 3 based color scheme (dark/light, 3 contrast levels per theme)
  • Centralized sizing control
  • Centralized font control
  • Automatic theme updates
  • Theme overrides

First you need to add sickle_ui as a dependency to your project:

[dependencies]
sickle_ui = "0.2.1"
# sickle_ui = { rev = "a548517", git = "https://github.com/UmbraLuminosa/sickle_ui" }

Once you have the new dependency, cargo build to download it. Now you are ready to use it, so add it to your app as a plugin:

use bevy::prelude::*;
use sickle_ui::{prelude::*, SickleUiPlugin};

fn main() {
  App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(SickleUiPlugin)
        // ... your actual app plugins and systems can go here of course
        .run();
}

The main SickleUiPlugin takes care of adding all the convenient features sickle_ui offers, and the sickle_ui::prelude::* brings into scope all available extensions. Have a look at the simple_editor example (that is displayed in the screenshot above) for how different parts work together.

In the most simple use cases you just want to use existing widgets to build up your UI. Sickle UI adds extensions to both Commands and EntityCommands, so in a regular system context you can quickly create a layout by calling a chain of functions. Comparing vanilla and Sickle UI:

In Bevy, you can use commands.spawn(bundle) and commands.entity(entity).with_children(builder) to spawn your entities. Typically, you would pass in a NodeBundle, ButtonBundle, or perhaps an ImageBundle just to name a few. Then, you can use the .with_children(builder) extension to spawn sub-entities. This will quickly become verbose and convulated with Rust's borrowing rules. It will be difficult to create entities with two way references between parent and children, elements further down the tree, or siblings.

fn setup(mut commands: Commands) {
  commands.spawn(NodeBundle {
      style: Style {
          height: Val::Percent(100.),
          flex_direction: FlexDirection::Column,
          ..default()
      },
      background_color: Color::NONE.into(),
      ..default()
  }).with_children(|parent|{
    parent.spawn(NodeBundle::default()).with_children(|parent|{
      // ...
    });
  });
}

The library takes care of this by abstracting widget creation behind builder extensions such as:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column.row(|row|{
      // ... etc.
    });
  });
}

While this may seem as a simple shorthand, the key difference is that column and row in the callbacks are contextual builders themselves and they give you access to commands and, where available, entity_commands. You can easily jump to another entity to insert components, style, or spawn new sub-entitites without tripping Rust's borrow checker.

Yes, you can also style entities spawned by the command chains, as simple as:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    // ...
  })
  .style()
  .width(Val::Percent(100.));
}

This means that in some cases, this also works as expected:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column
      .style()
      .width(Val::Percent(100.));
  });
}

The difference in the above is merely a styling choice of the developer (pun intended).

As mentioned, all builder function have a context.

• The root one is UiRoot. The entity spawned in the UiRoot context does not have a Parent entity, hence it will be a root Node.
• The most common regular context is Entity, which can be acquired by calling commands.ui_builder(entity). Where entity is an entity - ID - acquired by some other means, such as spawning or querying.

Fear not your column, or any other widget you create can be used like any other entity you have around. To just add a component:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|_|{}).insert(MyMarkerComponent);
}

You could capture its ID as well:

fn setup(mut commands: Commands) {
  let my_column = commands.ui_builder(UiRoot).column(|_|{}).id();

  // ... OR

  let my_column = commands.ui_builder(UiRoot).column(|_|{}).insert(MyMarkerComponent).id();
}

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column.insert(MyMarkerComponent); 
  });
}

If you just need a simple bundle somewhere in the tree, you can either use spawn or a container widget, like container to create or chain your one-off node. So, converting the bevy example we started with:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column.container(NodeBundle {
        style: Style {
            height: Val::Percent(100.),
            flex_direction: FlexDirection::Column,
            ..default()
        },
        background_color: Color::NONE.into(),
        ..default()
    }, |my_container|{
      // ... etc. my_container is an `Entity` context UiBuilder
    });
  });
}

If you do not even need to spawn children for this widget:

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column.spawn(NodeBundle {
        style: Style {
            height: Val::Percent(100.),
            flex_direction: FlexDirection::Column,
            ..default()
        },
        background_color: Color::NONE.into(),
        ..default()
    });
  });
}

fn setup(mut commands: Commands) {
  let mut inner_id = Entity::PLACEHOLDER;
  
  commands.spawn(NodeBundle {
      style: Style {
          height: Val::Percent(100.),
          flex_direction: FlexDirection::Column,
          ..default()
      },
      background_color: Color::NONE.into(),
      ..default()
  }).with_children(|parent|{
    inner_id = parent.spawn(NodeBundle::default()).with_children(|parent|{
      // ...
    }).id();
  });

  commands.ui_builder(inner_id).column(|column|{
    // Add a column into the inner entity and continue.
  });
}

fn setup(mut commands: Commands) {
  commands.ui_builder(UiRoot).column(|column|{
    column.row(|row|{
      let mut row_commands = row.entity_commands();
      row_commands.with_children(|parent| {
        // ... etc.
      });
    });
  });
}

Then you shall move on to the next section, Extending Sickle UI!

Sickle UI can be extended on multiple levels. Starting from the most simple one:

• Structural extensions
• Functional extensions
• Themed widgets
• Contextually themed widgets

These are however, NOT distinct extensions. Rather these are levels of customization you can apply to the widgets you create. If you don't need dynamic theming, you don't need to implement all that.

These are widgets that don't need systems and just create a pre-defined sub-tree that you can easily inject in the contexts you define them in. In this case you just need to create the relevant extension and describe your plugin structure using the technique described under OK, but I didn't find a widget I need

An example of this would be:

#[derive(Component, Debug, Default, Reflect)]
#[reflect(Component)]
pub struct MyWidget;

impl MyWidget {
    fn frame() -> impl Bundle {
        (Name::new("My Widget"), NodeBundle::default())
    }
}

pub trait UiMyWidgetExt {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity>;
}

impl UiMyWidgetExt for UiBuilder<'_, Entity> {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity> {
        self.container((MyWidget::frame(), MyWidget), spawn_children)
    }
}

You can then use your widget after bringing it into scope:

use my_widget::UiMyWidgetExt;

fn setup(mut commands: Commands) {
  // TODO: get your root entity where your widget will be added.
  // This could come from a query for example.
  let root_entity: Entity;
  commands.ui_builder(root_entity).my_widget(|my_widget|{
    // ... do more here!
  });
}

You may have noticed that the snippet extends the Entity context of UiBuilder. Your widget will be available in these contexts, provided you add the use my_widget::UiMyWidgetExt; to bring it in scope.

You may have also noticed that the snippet uses self to spawn the container. self will simply be a UiBuilder of the Entity context, so any other extensions that you brought into scope with use will be available. This also means that style commands are also available, so long as you have imported them.

Functional extension simply means that your widget does something beyond creating a pre-defined structure. You can use the snippet Sickle UI plugin widget to generate code similar to the one outlined in Structural extensions, with the addition of a plugin:

pub struct MyWidgetPlugin;

impl Plugin for MyWidgetPlugin {
    fn build(&self, _app: &mut App) {
        // TODO
    }
}

#[derive(Component, Debug, Default, Reflect)]
#[reflect(Component)]
pub struct MyWidget;

impl MyWidget {
    fn frame() -> impl Bundle {
        (Name::new("My Widget"), NodeBundle::default())
    }
}

pub trait UiMyWidgetExt {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity>;
}

impl UiMyWidgetExt for UiBuilder<'_, Entity> {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity> {
        self.container((MyWidget::frame(), MyWidget), spawn_children)
    }
}

All that is left is for you to implement the heart of the widget and the systems that act on it. Don't forget to add the generated plugin to your app!

Now, this is where the fun begins.

Themed widgets refer to widgets that have a style defined for them in a central place. However, themed widgets also allow overrides to their style, based on their position in the widget tree or their pseudo states.

Similarly to the previous cases, there is a snippet to generate the shell of a themed widget: The Sickle UI themed plugin widget.

pub struct MyWidgetPlugin;

impl Plugin for MyWidgetPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(ComponentThemePlugin::<MyWidget>::default());
    }
}

#[derive(Component, Clone, Debug, Default, Reflect, UiContext)]
#[reflect(Component)]
pub struct MyWidget;

impl DefaultTheme for MyWidget {
    fn default_theme() -> Option<Theme<MyWidget>> {
        MyWidget::theme().into()
    }
}

impl MyWidget {
    pub fn theme() -> Theme<MyWidget> {
        let base_theme = PseudoTheme::deferred(None, MyWidget::primary_style);
        Theme::new(vec![base_theme])
    }

    fn primary_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
        let theme_spacing = theme_data.spacing;
        let colors = theme_data.colors();

        style_builder
            .background_color(colors.surface(Surface::Surface))
            .padding(UiRect::all(Val::Px(theme_spacing.gaps.small)));
    }

    fn frame() -> impl Bundle {
        (Name::new("My Widget"), NodeBundle::default())
    }
}

pub trait UiMyWidgetExt {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity>;
}

impl UiMyWidgetExt for UiBuilder<'_, Entity> {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity> {
        self.container((MyWidget::frame(), MyWidget), spawn_children)
    }
}

While we have seen most of the above from the previous snippets, there are a couple additions.

First, an additional plugin has been injected to our app in the widget's plugin definition:

impl Plugin for MyWidgetPlugin {
    fn build(&self, app: &mut App) {
        // This here is very important!
        app.add_plugins(ComponentThemePlugin::<MyWidget>::default());
    }
}

The ComponentThemePlugin handles theme calculation and reloading for the component is added for. In this case we added it for MyWidget, which is the example component.

Next, we have the implementation of DefaultTheme:

impl DefaultTheme for MyWidget {
    fn default_theme() -> Option<Theme<MyWidget>> {
        MyWidget::theme().into()
    }
}

This is the theme that will be applied (unless it returns None) to any widget in the widget tree that has no overrides on any of its ancestors. We will look at how this works exactly in the Theming section.

For now, the key point is that it is generally desirable to implement the default theme of the widget as part of this implementation so an explicit injection is not needed or a sane fallback is provided.

The last part is the actual definition of the theme as part of the widget's impl block:

impl MyWidget {
    pub fn theme() -> Theme<MyWidget> {
        let base_theme = PseudoTheme::deferred(None, MyWidget::primary_style);
        Theme::new(vec![base_theme])
    }

    fn primary_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
        let theme_spacing = theme_data.spacing;
        let colors = theme_data.colors();

        style_builder
            .background_color(colors.surface(Surface::Surface))
            .padding(UiRect::all(Val::Px(theme_spacing.gaps.small)));
    }

    // ...
}

The two function above define the theme itself and the styling that is applied as part of the PseudoTheme of None. This is simply the style that is applied when the widget has no special PseudoState attached to it. It is the base theme and the fallback style that is always applied to any new entities that are added to the widget tree. It is also the basis of any overrides.

In the simplest use case, defining the style is just a matter of calling style function on the provided style_builder. The methods available here are the same as the ones provided by the UiStyle extensions outlined in Did I mention style? with a few additions.

With this, we have a convenient place to implement all our styling needs.

Contextually themed widgets take Themed widgets a step further by allowing the styling to be applied to sub-widgets defined as part of the main widget. The snippet Sickle UI contexted themed plugin widget generates the following shell:

pub struct MyWidgetPlugin;

impl Plugin for MyWidgetPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(ComponentThemePlugin::<MyWidget>::default());
    }
}

#[derive(Component, Clone, Debug, Reflect)]
#[reflect(Component)]
pub struct MyWidget {
    label: Entity,
}

impl Default for MyWidget {
    fn default() -> Self {
        Self {
            label: Entity::PLACEHOLDER,
        }
    }
}

impl DefaultTheme for MyWidget {
    fn default_theme() -> Option<Theme<MyWidget>> {
        MyWidget::theme().into()
    }
}

impl UiContext for MyWidget {
    fn get(&self, target: &str) -> Result<Entity, String> {
        match target {
            MyWidget::LABEL => Ok(self.label),
            _ => Err(format!(
                "{} doesn't exist for MyWidget. Possible contexts: {:?}",
                target,
                self.contexts()
            )),
        }
    }

    fn contexts(&self) -> Vec<&'static str> {
        vec![MyWidget::LABEL]
    }
}

impl MyWidget {
    pub const LABEL: &'static str = "Label";

    pub fn theme() -> Theme<MyWidget> {
        let base_theme = PseudoTheme::deferred(None, MyWidget::primary_style);
        Theme::new(vec![base_theme])
    }

    fn primary_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
        let theme_spacing = theme_data.spacing;
        let colors = theme_data.colors();
        let font = theme_data
            .text
            .get(FontStyle::Body, FontScale::Medium, FontType::Regular);

        style_builder
            .background_color(colors.surface(Surface::Surface))
            .padding(UiRect::all(Val::Px(theme_spacing.gaps.small)));

        style_builder
            .switch_target(MyWidget::LABEL)
            .sized_font(font);
    }

    fn frame() -> impl Bundle {
        (Name::new("My Widget"), NodeBundle::default())
    }
}

pub trait UiMyWidgetExt {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity>;
}

impl UiMyWidgetExt for UiBuilder<'_, Entity> {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity> {
        let label = self
            .label(LabelConfig {
                label: "MyWidget".into(),
                ..default()
            })
            .id();

        self.container((MyWidget::frame(), MyWidget { label }), spawn_children)
    }
}

Now, our widget component is no longer just a tag. It now has a reference to a label sub-widget:

#[derive(Component, Clone, Debug, Reflect)]
#[reflect(Component)]
pub struct MyWidget {
    label: Entity,
}

impl Default for MyWidget {
    fn default() -> Self {
        Self {
            label: Entity::PLACEHOLDER,
        }
    }
}

// ...

impl UiMyWidgetExt for UiBuilder<'_, Entity> {
    fn my_widget(
        &mut self,
        spawn_children: impl FnOnce(&mut UiBuilder<Entity>),
    ) -> UiBuilder<Entity> {
        let label = self
            .label(LabelConfig {
                label: "MyWidget".into(),
                ..default()
            })
            .id();

        self.container((MyWidget::frame(), MyWidget { label }), spawn_children)
    }
}

We need to implement Default for it manually, since Entity has no default. Using Entity::PLACEHOLDER is alright as long as we make sure we always assign an actual entity to it (otherwise it will panic!).

But this isnt't the only addition. Now our snippet defined an implementation for UiContext we previously got from a simple derive:

impl UiContext for MyWidget {
    fn get(&self, target: &str) -> Result<Entity, String> {
        match target {
            MyWidget::LABEL => Ok(self.label),
            _ => Err(format!(
                "{} doesn't exist for MyWidget. Possible contexts: {:?}",
                target,
                self.contexts()
            )),
        }
    }

    fn contexts(&self) -> Vec<&'static str> {
        vec![MyWidget::LABEL]
    }
}

This tells the theming system that MyWidget has a single additional context (besides the main entity). The additional context can be accessed by the MyWidget::LABEL constant, which was added to the impl block:

impl MyWidget {
    pub const LABEL: &'static str = "Label";

    // ...
}

Further down we can also see a change: The primary_style now applies styling to the label!

impl MyWidget {
    // ...

    fn primary_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
        let theme_spacing = theme_data.spacing;
        let colors = theme_data.colors();
        let font = theme_data
            .text
            .get(FontStyle::Body, FontScale::Medium, FontType::Regular);

        style_builder
            .background_color(colors.surface(Surface::Surface))
            .padding(UiRect::all(Val::Px(theme_spacing.gaps.small)));

        style_builder
            .switch_target(MyWidget::LABEL)
            .sized_font(font);
    }

    // ...
}

In the above code, there is a call on style_builder to switch_target to our label and set its font size. Refer to Style builder for how this works in detail.

In a nutshell, yes. If you use the snippets, you can quickly set up a complex widget tree and define each sub-widget's style by chaining the calls to the style_builder. Of course, there are other ways to interact with the theming process, such as accesing the world or the current widget component, but the heart of it is the same: A theme, made up of pseudo themes that build the styling of the widget and its sub-widgets.

Theming is the process of applying styling on an entity (Node) based on its position in the widget tree, function, and current state. A Theme is a collection of PseudoThemes, which define the style for an entity when it has the relevant PseudoStates in its PseudoStates collection component.

Styling is done per-attribute, meaning each stylable attribute has its own entry in the final DynamicStyle component attached to the entity. Each Theme and their PseudoThemes are evaluated in a strict order to calculate the final style for each attribute.

When a themed component is added to the hierarchy, the system will look for all Theme components in its chain of ancestors (including itself) until it reaches a root entity. DefaultTheme implementations are checked last. Once the list of applicable Themes are found, they are evaluated in reverse order. This means that the DefaultTheme is the first that will be evaluated, then any override starting from the root entity, down to the themed entity itself.

Once we have the list of Themes, each theme is expanded to collect the applicable PseudoThemes in their order of specificity. A PseudoTheme is considered if, and only if, all of the PseudoStates it was defined for is on the entity. However, if it only defines a subset of PseudoStates it will still be considered, but before the ones that fully cover the states.

If an entity has the PseudoStates [Checked, Disabled, FirstChild] then PseudoThemes defined for None, [Checked], [Disabled], [FirstChild], [Checked, Disabled], [Checked, FirstChild], and [Checked, Disabled, FirstChild] will be considered, in this order.

If the entity only has the [Checked] state, then PseudoThemes defined for None, and [Checked] will be applied, but none of the others because they are either defined for a disjoint set or they are not a complete subset of the entity's state.

If the ComponentThemePlugin:: is in place, the following changes trigger themes to be processed for the managed component C:

• Entity added with C: The theme for each new entity will be evaluated and applied
• Theme data resource changed: All entities with C will be processed
• Any Theme<C> added, changed, or removed: All entities with C will be processed
• Any entity with component C will be re-processed if their PseudoStates changes (or if it has been removed).

No.

Still no. Themes are related to components, and there is no theme merging across components. This is because sickle_ui does not support defining relation between component themes to achieve this (for multiple reasons).

HOWEVER! If we are talking about the case where developers no longer use the C in CSS it is possible.

Modern web development usually follows some sort of style simplification to avoid running into issues with ambigous specificities or the performance cost of deeply nested styles (not to mention minimization). One widespread method is to use the BEM (Block, Element, Modifier) notation to compose class names. Combined with a pre-processor like SASS and some discipline, most single page apps have a single-level nested style sheet.

Parsing such a style sheet, generating a bevy component for each of the classes, then transforming the style to themes should be entirely possible. Because of how theme overrides work some nesting can also be achieved so long as two themes don't style the same entity. To make this work well, the brave developer would need to implement:

• A setup that removes nesting from raw CSS (BEM + SASS is a good starting point)
• Something* to parse the above mentioned "flat" CSS to generate components and themes
• Systems that automatically inject theme overrides to achieve nesting
• And finally some systems to automatically apply PseudoStates matching that of CSS. See PseudoStates for what is already implemented and how to use it.

No.

Theme<C + DefaultTheme> is a bevy component used to hold PseudoThemes. Inserting a Theme::<C> component in the widget tree will override styling for C components below (or on) it.

PseudoTheme<C> is a carrier struct to map a list of PseudoStates to builders for styling. While this struct can be created directly with a DynamicStyleBuilder variant, it is recommended to use one of the exposed function:

• PseudoTheme::build
• PseudoTheme::deferred
• PseudoTheme::deferred_context
• PseudoTheme::deferred_world
• PseudoTheme::deferred_info_world

build requires a simple callback that accepts a StyleBuilder instance to setup the entity style. This style builder is immediately evaluated to generate the DynamicStyle that will be cloned to entities. Switching context on the style builder emits a warning. This is because the target context cannot be known at compile time.

Deferred builders are stored as callbacks and evaluated when the theming system is applying styling. Depending on the variant you use, the callback will receive a different set of parameters:

• deferred will receive the style builder and the theme data resource
• deferred_context will additionally receive &C, which is a reference to the styled component instance.
• deferred_world will receive the entity (ID), &C, and a readonly reference to the World.
• deferred_info_world will additionally receive the ID of the theme that is being applied and the set of PseudoStates. These are both optional as the theming could be done from the DefaultTheme for the base pseudo theme (defined for None). This callback is useful if the whole context is needed to map a callback to an external stylesheet implementation.

PseudoStates is a bevy component with the sole purpose of holding PseudoState variants. This component is monitored by the ComponentThemePlugin, see What triggers theming? for how it ties into it.

EntityCommands extensions are provided with the trait ManagePseudoStateExt to manage the list as follows:

• add_pseudo_state: used to add a PseudoState
• remove_pseudo_state: used to remove a PseudoState

There are a couple of systems that automatically apply certain PseudoStates to entities, but these are all opt-in:

• Entities tagged with FlexDirectionToPseudoState will be processed to set either PseudoState::LayoutRow or PseudoState::LayoutColumn based on their Style's flex_direction. The update is done in PostUpdate before ThemeUpdate, so themes will automatically process changes in layout.
• Entities tagged with VisibilityToPseudoState will be processed to set or remove PseudoState::Visible from their list of PseudoStates. This update considers actual visibility based on the entity's Visibility and InheritedVisibility, updated only on changes to either of these. The update is done in PostUpdate, after VisibilitySystems::VisibilityPropagate, but before ThemeUpdate.
• An entity's position among its siblings with component C can be tracked with the HierarchyToPseudoState::<C> plugin. This plugin will set PseudoState::FirstChild, PseudoState::LastChild, PseudoState::NthChild(i), PseudoState::SingleChild, PseudoState::EvenChild, and PseudoState::OddChild as appropriate. This is also done in PostUpdate before ThemeUpdate.

Most build-in widgets will also set PseudoStates based on user interaction, such as a Dropdown will set PseudoState::Open when the list of options should be visible, etc.. These are documented on the UiBuilder extensions themselves.

Don't you worry, there is a PseudoState::Custom(String) specifically for such use cases.

The style builder is the recommended way of generating DynamicStyle components as it lets developers chain together style attributes in a consistent fashion. On top of what UiStyle extensions allow, the style builder also adds interactive and animated properties. These properties tie into interactions from the user, such as hover, press, etc. to change styled attributes.

The distinction between interactive and animated is that interactive styles apply immediately when an interaction occurs. animated attributes perform some eased interpolation between start and end values to apply the final style.

In case you want to use the StyleBuilder without the PseudoTheme fluff, you can simply create an instance:

let mut style_builder = StyleBuilder::new();
style_builder
    .width(Val::Percent(100.))
    .height(Val::Percent(100.));

let dynamic_style: DynamicStyle = style_builder.into();
// Insert the dynamic stlye to your entity as any other `bevy` component.

fn interactive_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
    style_builder
        .interactive()
        .width(InteractiveVals {
            idle: Val::Px(100.),
            hover: Val::Px(120.).into(),
            ..default()
        })
        .height(InteractiveVals {
            idle: Val::Px(100.),
            press: Val::Px(120.).into(),
            ..default()
        });
}

fn animated_style(style_builder: &mut StyleBuilder, theme_data: &ThemeData) {
    let theme_spacing = theme_data.spacing;

    style_builder
        .animated()
        .margin(AnimatedVals {
            idle: UiRect::all(Val::Px(theme_spacing.gaps.medium)),
            hover: UiRect::all(Val::Px(0.)).into(),
            ..default()
        })
        .copy_from(theme_data.interaction_animation);

    style_builder
        .animated()
        .scale(AnimatedVals {
            idle: 1.,
            enter_from: Some(0.),
            ..default()
        })
        .copy_from(theme_data.enter_animation);
}

As described in Contextually themed widgets, widget components can manually implement The UiContext to provide additional styling targets / placements.

Switching target on the style builder configures subsequent calls to target an entity other than the main one. The string labels used to identify targets are mapped to entities during the theme building process. The targets can only be entity properties of the widget component. To revert back to styling the main widget, call reset_target on the style builder. Internally, the target is an Option and None always means "target the entity the DynamicStyle component is on".

An example would be the checkbox, that applies styling to both the box and the label when the whole container is interacted.

Switching placement, as opposed to switching the target of styling, changes where the DynamicStyle component will be injected. This means that interactions will be detected on the placement and thus can narrow down interactive area to sub-entities. Calling reset_placement reverts the builder to add attributes to the DynamicStyle of the main entity. Internally placement is an Option, and None means that new attributes are collected for the main entity being styled.

Switching context combines setting placement and target together, and is the recommended way to interact with the builder to change placements. This is because the target may remain from a previous call and cause unwanted styling. Call reset_context on the style builder to remove both placement and target setting.

Don't worry, sickle_ui got you covered!

All attribute types (static, interactive, animated) support a custom variant, that can be provided as a callback. static attributes receive the Entity and &mut World as arguments. interactive callbacks will receive the Entity, FluxInteraction, and &mut World, while animated callbacks will receive Entity, AnimationState, &mut World.

You are free to mess up the whole wide world in these callbacks, no guarantees it won't blow up in your face :D

DynamicStyle is a bevy component used to store the list of attributes that should be applied to the entity during its PostUpdate execution. The system set DynamicStylePostUpdate is available for scheduling purposes and it will always run after theming, but before UiSystem::Layout.

Systems acting on this component apply the static styling immediately when the DynamicStyle changes, and will keep track and execute interactive and animated attribute application.

Theme data is an opinionated struct containing values useful for general purpose UI styling. Currently, it has colors loosely matching a Material3 theme, a set of gap sizes, area sizes, input sizes, font configuration, etc.

Any sickle_ui widget that has variable values will depend on the default theme data.

There are a number of utilities that form the foundation of sickle_ui widgets and can be reused for new widgets just as well.

FluxInteraction is the basis of all interactivity in sickle_ui. It is a wrapper around the built-in Interaction but instead of tracking current state it tracks transitions from one state to another.

FluxInteractionStopwatch keeps track of the time elapsed since the last change to the FluxInteraction of an entity. This stopwatch by default is available for 1 second after every change for performance reasons. The resource FluxInteractionConfig can be used to control the time it is available, though it is not recommended to change this. Instead, FluxInteractionStopwatchLocks can be used to extend or precise the time the stopwatch needs to be available.

The recommended way of adding FluxInteraction to an entity is by using the provided TrackedInteraction bundle.

Scroll interactions can be intercepted by the Scrollable component attached to an entity. Systems relying on it can use Changed<Scrollable> as a filter to optimize updates.

The Draggable component is built around FluxInteraction and RelativeCursorPosition to translate interactions to drag intents. The component itself doesn't do anything besides tracking the drag intents. Developers wishing to utilize it can rely on change detection and use the provided values to update aspects of their widgets, i.e. scroll bars can be dragged to scroll content, resize handles can be dragged to change the size of their parent, etc.

Draggable, Droppable, and DropZone together forms the drop interactions. When a Droppable is being dragged over a DropZone, the zone will hold a reference to the entity being dragged. It is up to the developer to check if the source entity is acceptable and to indicate the drop action status.

Resize handles can be easily added to any widget, however these are just pre-styled draggables. They don't automatically update the size of their container.

PseudoState::Resizable(_) states can be added to the outermost container to control which handle is interactible.

The UiContextRoot is a marker component intended to signal logical UI roots. The component is used by context menus and tab container to find mounting points for spawned entites. In the case of context menus, the menu itself will be mounted at this root. In the case of the tab container the floating panel that is opened when a tab is "popped out" is mounted at the context root.

UiUtils is a collection of useful UI logic, such as converting between variants of Val or finding UI viewports.

A number of Commands extension is available to make life easier, such as managing PseudoStates, FluxInteractionStopwatchLocks, or logging an entity's hierarchy and components.

The context menu system in sickle_ui relies on reflection to allow any component to generate its own entires to the context menu.

To implement a context menu for a widget two steps are necessary:

• An Interaction entity needs to be tagged with the GenerateContextMenu component to signal support.
• At least one component on the entity needs to implement ContextMenuGenerator and register its type.

impl Plugin for MyContextMenuPlugin {
    fn build(&self, app: &mut App) {
        app.register_type::<MyComponent>();
    }
}

#[derive(Component, Clone, Debug, Reflect)]
#[reflect(Component, ContextMenuGenerator)]
pub struct MyComponent;


impl ContextMenuGenerator for MyComponent {
    fn build_context_menu(&self, context: Entity, container: &mut UiBuilder<ContextMenu>) {
        // Add menu items as needed to the container.
        
        container
            .menu_item(MenuItemConfig {
                name: "Open in new".into(),
                trailing_icon: icons.open_in_new,
                ..default()
            })
            // OpenInNewFromContextMenu is an examle component that another system could track
            // and execute the operation when the menu item is interacted.
            .insert(OpenInNewFromContextMenu { context });
    }

    fn placement_index(&self) -> usize {
        0
    }
}

The above example is the preparation for filling a context menu, but the menu item will only show up in a context menu if the entity has Interaction and GenerateContextMenu::default() attached to it.

Style attributes can sometimes be locked. This is to prevent accidental styling of parts that have a function and are driven by a widget's own system. Attempting to style or theme a locked attribute results in a warning being emitted (and no change applied to the attribute).

Sometimes it is useful to track the overall state of styling application. sickle_ui provides a "meta" style attribute called TrackedStyleState that can be used to drive other widgets from DynamicStyles. It does not actually style anything.