bevy_ui_builder 0.1.0

ui builder library for bevy_ui
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

# Bevy UI Builder


Simple ui builder, a simple wrapper of bevy_ui, fluent api design.

## Warning


Under heavy development, cannot guarantee API stability.

## Features


- build bevy_ui basic elements: node, text, image, button
- various buttons, includes
    - toggle button
    - click action on mouse button release inside
- various binding

## Basics


### Construct ui hierarchy


before start, you need to know about bevy_ui 4 basic ui elements

- node(NodeBundle)
- image(ImageBundle)
- text(TextBundle)
- button(ButtonBundle)

ui builder has corresponding functions to build entire ui

- node()
- image(handle_to_image)
- button()
- text(content)

```rust
// before start, add plugin first
.add_plugin(UiBuilderPlugin)

// usage
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    // ...
    let mut b = UiBuilder::new(&mut commands, ());
    // create new node element
    b.node()
        // style modifier
        .with_style_modifier((StyleSize::FULL, StyleCenterChildren))
        .with_children(|b| {
            // create image element
            b.image(asset_server.load("image/file.png"));
            // create button element
            b.button()
                .with_children(|b| {
                    // create text element
                    b.text("text content");
                });
        });
    // ...
}
```

### Modify style


- change `Style` component with `.with_style_modifiers(...)`
- change `Text` component with `.with_text_modifier(...)`
- change `Visibility` component with `.with_visibility(...)`
- change `BackgroundColor` component with `.with_bg_color(...)`

> NOTE: duplicated call will overwrite previous state

For more `StyleModifier` and `TextModifier` , please see [src/modifiers.rs](src/modifiers.rs)

### Buttons


There is a button [example](examples/buttons.rs)



#### Toggle Button


- toggle button: `.with_toggle(false)`
- toggle button with toggle group: `.with_toggle(false).with_toggle_group("group_name")`

#### Click Action


- `.with_action_on_release()`: action performed on mouse button release inside
- `.with_mouse_button_mask(...)`: react on additional mouse right / middle button, or can disable default left mouse button

#### Button Visual


every button has following visual states,

- normal
- disabled
- normal_hovered
- pressed
- pressed_hovered

library provide following two ways

- `.with_image_button()`: change UiImage when visual state change.
- `.with_color_button()`: change BackgroundColor when visual state change.

If you need more customize style, you can use `Changed<>` subscribe `ButtonVisualState` component changes, and work on your styles.

### Data Binding


- S: data source, component
- T: modify target, component
- source entity: has a data source component `S`
- target entity: has target component `T`

| api                                                  | description                                                  |
| ---------------------------------------------------- | ------------------------------------------------------------ |
| `with_bind_source::<S, T>(source, handler)`          | when remote entity `source` component `S` change, call handler function to modify current entity component `T`. see [example](examples/bind_source.rs) |
| `with_on_self_change::<S>(handler)`                  | when current entity component `S` change, call handler function. see [example](examples/on_self_change.rs) |
| `with_event_bind_to_target::<E, T>(target, handler)` | when event E happen, call handler function to modify entity `target` component `T`. see [example](examples/inventory.rs) |
| `with_on_source_change::<S>(source, handler)`        | when remote entity `source` component `S` change, call handler function. see [example](examples/inventory.rs) |
| `with_self_bind::<S, T>(handler)`                    | when current entity component `S` change, call handler function to modify current entity component `T`. see [example](examples/self_bind.rs) |
| `with_bind_to_target::<S, T>(target, handler)`       | when current entity component `S` change, call handler function to modify remote entity `target` component `T`. see [example](examples/bind_to_target.rs) |
| `with_bind_to_multiple_targets::<S, T>(binds)`       | when current entity component `S` change, call handler function to modify remote entity `target` component `T` |

## Compatible bevy version


| bevy | bevy_ui_builder |
| ---- | --------------- |
| 0.9  | 0.1             |

## Similar Projects


This library is inspired from following libraries

- https://github.com/Anti-Alias/bevy_ui_dsl
- https://github.com/TheRawMeatball/ui4

## License


MIT OR Apache-2.0