TOMT BevyCSS

What is TOMT BevyCSS?

TOMT BevyCSS is a fork project derived from Bevy ECSS is a crate which allows the usage of a subset of CSS to interact with bevy_ecs. It's mainly aimed to apply styling on bevy_ui but it can be used by any component by implementing custom properties.

Package name?

TOMT = Tome of Many Things
BevyCSS = Bevy + CSS, This library brings CSS features into the Bevy UI

Who is TOMT (Tome of Many Things)?

Tome of Many Things is a small friendship group with various internet projects, primarily focussing on the Tome of Many Things YouTube channel.

This library project is brought to you by TheBeardedQuack (BitBucket, YouTube). Forked from BevyECSS, and released under the same MIT and Apahe v2.0 licences to allow for continued freedom of use, modification and distribution.

Usage

To use TOMTBevyCSS just add a StyleSheet with a loaded css file to any entity and all style sheet rules will be applied to the entity and _all its descendants (children of children of children and so on).

```rust use bevy::prelude::; use tomt_bevycss::prelude::;

fn setupawesomeui(root: Entity, mut commands: Commands, assetserver: Res) { commands .entity(root) .insert(StyleSheet::new(assetserver.load("sheets/awesome.css"))); } ```

That's it, now your UI will indeed look awesome!

CSS Subset

TOMT_BevyCSS only supports a subset of CSS at moment, since many properties and features requires more advanced selectors, components and properties which currently isn't implemented. The goal of this fork however, is to develop additional CSS comforts like additional selectors, and color functions.

Here you can find a list of all currently supported selectors and properties:

Selectors

| Type | Details | Example | | :---------: | :------------------------------------------------------------------------------------------------------------ | :------------------- | | Name | Selects by using bevy built-int Name component. | #inventory { ... } | | Class | Selects by using Class component, which is provided by TOMTBevyCSS. | .enabled { ... } | | _Component | Selects by using any component, but it has to be registered before usage. You can find more details bellow. | button { ... } | | PseudoClass | Selects by using an internal list of known rules run over ECS hierarchy. | :hover { ... }

You may combine any of the above selector types to create a complex selector, if you like so. For instance, window.enabled.pop-up select all windows, which are enabled and are of pop-up type. The same rules of CSS Class selectors applies here.

This assumes that window is a bevy_ecs component and was registered before usage. Also assumes the entities has the Class component with at least enabled pop-up class name.

Aditionally, TOMTBevyCSS also supports descendant combinator which selects _all entities that are descendant the given selector tree.

```css

quest-window text {

color: red;

} ```

The above rule will match all entities which has a Text component and is descendant of any entity which as a Name component which the value of quest-window.

So it's possible to combine complex composed selectors with descendant combinator.

```css

main-menu button.enabled .border {

background-color: #ff03ab;

} ```

This rule will match all components which has a Class with the value of border and are descendant of any entity which has a button component and a Class component with the value of enabled and also are descendant of any entity which has a Name component with value main-menu.

Properties

Here is a list of all currently supported properties. Note that these are properties which are provived by TOMT_BevyCSS but you can also add your own properties at anytime.

Before reading properties description, we'll use this notation to describe accepted values:

| Notation | Description | | :--------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 00.00% | Any percent value, like 93% or 4.45% | | 00.00px | Any dimensional value, like 11px or 0.99px | | 00.00 | Any number value, like 0 or 14.2 | | <ident> \| <ident> | Only one of the identifiers are allowed, without quotes, like none or hidden | | <area-short-hand> | Allows the short hand area constructor by using either dimensions or percentage, like 10px or 5% 10px 3% auto. No global values are supported yet |

`Style` properties

`Text` properties

Components properties

| Property | Values | Description | | :----------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------- | | background-color | named-colors \| hex_colors | Applies the property on BackgroundColor of all matched components. |

Component Selector Builtin

TOMT_BevyCSS provides the following component selectors:

This list will be expanded to match bevy_ui and other bevy core components.

PseudoClass Selector Builtin

TOMT_BevyCSS provides the following pseudo-class selector:

This list will be exanpded as additional selectors are added into this library.

Custom Component Selector

You may also register your own components or alias/overwrite builtin components selector. ```rust use bevy::prelude::; use tomt_bevycss::prelude::;

[derive(Component)]

struct MyFancyComponentSelector;

[derive(Component)]

struct FancyColor;

fn somemain() { let mut app = App::new(); app.addplugins(DefaultPlugins).addplugin(BevyCssPlugin::default()); // You may use it as selector now, like // fancy-pants { // background-color: pink; // } app.registercomponentselector::("fancy-pants"); // Or you can overwrite a component selector. app.registercomponent_selector::("background-color"); } ```

Custom Property

It's also possible to implement your own properties, be it part of CSS standard or not. Let's implement a custom alpha property with will set the alpha channel of any BackgroundColor. ```rust

use bevy::{

ecs::query::QueryItem,

prelude::*

};

use tomt_bevycss::prelude::*;

[derive(Default)]

pub(crate) struct AlphaProperty;

impl Property for AlphaProperty { // This is the cached value to be used when applying the property value. // It is evaluated only on the first time and futures runs are cached for performance reasons. type Cache = f32; // Which components the property needs when applying the cached value. // It is the same as using bevy_ecs Query. type Components = &'static mut BackgroundColor; // If this property can be set only when there is another property, it's possible to filter here. // It's not recommended to use only With<> and Without<>. type Filters = ();

fn name() -> &'static str {
    // The name of property. prefer kebab-case for consistency.
    "alpha"
}

fn parse<'a>(values: &PropertyValues) -> Result<Self::Cache, BevyCssError> {
    // PropertyValues::f32 tries to parse property value into a numeric value
    if let Some(value) = values.f32() {
        Ok(value)
    } else {
        Err(BevyCssError::InvalidPropertyValue(Self::name().to_string()))
    }
}

// This function will be called for every entity matched on every rule selector.
fn apply<'w>(
    cache: &Self::Cache,
    mut components: QueryItem<Self::Components>,
    _asset_server: &AssetServer,
    _commands: &mut Commands,
) {
    components.0.set_a(*cache);
}

} ```

Now just register the property on App: rust ignore app.register_property::<AlphaProperty>();

Done! Whenever an alpha property is found on any css file, the AlphaProperty will be applied. You can find this full example here.

Bevy support table

| bevy | tomt_bevycss | | :---: | :-------: | | 0.8 | 0.1 | | 0.9 | 0.2 | | 0.10 | 0.3 |

Contributing

Got some idea, feedback, question or found any bug? Feel free to open an issue at any time!

License

TOMT_BevyCSS is dual-licensed under either:

MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are very good reasons to include both.

TOMT BevyCSS

What is TOMT BevyCSS?

Package name?

Who is TOMT (Tome of Many Things)?

Usage

CSS Subset

Selectors

quest-window text {

main-menu button.enabled .border {

Properties

Style properties

Text properties

Components properties

Component Selector Builtin

PseudoClass Selector Builtin

Custom Component Selector

[derive(Component)]

[derive(Component)]

Custom Property

use bevy::{

ecs::query::QueryItem,

prelude::*

};

use tomt_bevycss::prelude::*;

[derive(Default)]

Bevy support table

Contributing

License

`Style` properties

`Text` properties