diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 673f1ff9..1f86b92f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,12 +2,12 @@ Floem aims to be a high performance UI library. New contributions are always welcome! -To start with, the best way to learn how Floem works is probably to look at the examples. And if you think there are more examples that can be added, feel free to send a PR in. +The best way to start contributing to Floem is to learn how it works by looking at the examples. If you think there are more examples that can be added, feel free to send in a PR! -Alternatively, you can have a look at issues, to see if there's anything you'd like to pick up. +Alternatively, you can have a look at issues to see if there is anything you'd like to pick up. -Firing bugs with clear reproducing steps is a really good way of contributing as well. +Filing bugs with clear, reproducible steps is a great way to contribute as well. -It's not a good library if there isn't good documentation. So any documentation contributions will be much appreciated. +It's not a good library if there isn't good documentation. So, all contributions to the documentation are very appreciated! -If you'd like a conversation with Floem devs, you can join in the #floem channel on this [Discord](https://discord.gg/RB6cRYerXX). \ No newline at end of file +If you would like a conversation with the devlopers of Floem, you can join in the #floem channel on this [Discord](https://discord.gg/RB6cRYerXX). diff --git a/README.md b/README.md index 250c5374..3e31857e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@
+ # Floem A native Rust UI library with fine-grained reactivity @@ -15,46 +16,43 @@ _The project is still maturing. We will make occasional breaking changes and add ## Quickstart -![Quickstart](docs/img/quickstart.png) - ```rust -use floem::{ - reactive::create_signal, - views::{button, label, Decorators}, - IntoView, -}; - -fn app_view() -> impl IntoView { - // Create a reactive signal with a counter value, defaulting to 0 - let (counter, mut set_counter) = create_signal(0); - - // Create a vertical layout - ( - // The counter value updates automatically, thanks to reactivity - label(move || format!("Value: {counter}")), - // Create a horizontal layout - ( - button("Increment").action(move || set_counter += 1), - button("Decrement").action(move || set_counter -= 1), - ), - ).style(|s| s.flex_col()) -} +use floem::prelude::*; fn main() { - floem::launch(app_view); + floem::launch(counter_view); +} + +fn counter_view() -> impl IntoView { + let mut counter = RwSignal::new(0); + + h_stack(( + button("Increment").action(move || counter += 1), + label(move || format!("Value: {counter}")), + button("Decrement").action(move || counter -= 1), + )) + .style(|s| s.size_full().items_center().justify_center().gap(10)) } + ``` + + + + ## Features -Inspired by [Xilem](https://github.com/linebender/xilem), [Leptos](https://github.com/leptos-rs/leptos) and [rui](https://github.com/audulus/rui), Floem aims to be a high performance declarative UI library requiring minimal user effort. +Inspired by [Xilem](https://github.com/linebender/xilem), [Leptos](https://github.com/leptos-rs/leptos) and [rui](https://github.com/audulus/rui), Floem aims to be a high performance declarative UI library with a highly ergonomic API. -- **Cross-platform support**: Supports Windows, macOS and Linux with rendering using [wgpu](https://github.com/gfx-rs/wgpu). In case a GPU is unavailable, a CPU renderer powered by [tiny-skia](https://github.com/RazrFalcon/tiny-skia) will be used. +- **Cross-platform**: Floem supports Windows, macOS and Linux with rendering using [wgpu](https://github.com/gfx-rs/wgpu). In case a GPU is unavailable, a CPU renderer powered by [tiny-skia](https://github.com/RazrFalcon/tiny-skia) will be used. - **Fine-grained reactivity**: The entire library is built around reactive primitives inspired by [leptos_reactive](https://crates.io/crates/leptos_reactive). The reactive "signals" allow you to keep your UI up-to-date with minimal effort, all while maintaining very high performance. -- **Performance**: The view tree is only run once, safeguarding you from accidentally creating a bottleneck in a view generation function that slows down your entire application. Floem also provides tools to help you write efficient UI code, such as a [virtual list](https://github.com/lapce/floem/tree/main/examples/virtual_list). -- **Flexbox layout**: Using [Taffy](https://crates.io/crates/taffy), the library provides the Flexbox (or Grid) layout system, which can be applied to any View node. -- **Customizable widgets**: Don't want the default look? You can change pretty much anything you want using the styling API, or install a third-party theme. -- **Element inspector**: Inspired by your browser's developer tools, Floem provides a [diagnostic tool](https://lapce.dev/floem/floem/id/struct.Id.html#method.inspect) to debug your layout. +- **Performance**: The view tree is constructed only once, safeguarding you from accidentally creating a bottleneck in a view generation function that slows down your entire application. Floem also provides tools to help you write efficient UI code, such as a [virtual list](https://github.com/lapce/floem/tree/main/examples/virtual_list). +- **Ergonomic API**: Floem aspires to have a highly ergonmic API that is a joy to use. +- **Flexbox layout**: Using [Taffy](https://crates.io/crates/taffy), the library provides the Flexbox and Grid layout systems, which can be applied to any View node. +- **Customizable widgets**: Widgets are highly customizable. You can customize both the appearance and behavior of widgets using the styling API, which supports theming with classes. You can also install third-party themes. +- **Transitions and Animations**: Floem supports both transitions and animations. Transitions, like css transitions, can animate any property that can be interpolated and can be applied alongside other styles, including in classes. + Floem also supports full keyframe animations that build on the ergonomics of the style system. In both transitions and animations, Floem supports easing with spring functions. +- **Element inspector**: Inspired by your browser's developer tools, Floem provides a [diagnostic tool](docs/img/inspector.png) to debug your layout. To sample Floem's capabilities, check out the repo and run the [widget gallery](examples/widget-gallery/src/main.rs) example with cargo. diff --git a/docs/img/inspector.png b/docs/img/inspector.png new file mode 100644 index 00000000..a1397fdc Binary files /dev/null and b/docs/img/inspector.png differ diff --git a/docs/img/quickstart.png b/docs/img/quickstart.png index 4960273d..03d5c415 100644 Binary files a/docs/img/quickstart.png and b/docs/img/quickstart.png differ diff --git a/docs/img/widget-gallery.png b/docs/img/widget-gallery.png index bbca914f..c3e3b56a 100644 Binary files a/docs/img/widget-gallery.png and b/docs/img/widget-gallery.png differ diff --git a/examples/virtual_list/README.md b/examples/virtual_list/README.md index 4ae5aca6..42f74388 100644 --- a/examples/virtual_list/README.md +++ b/examples/virtual_list/README.md @@ -1,5 +1,5 @@ -In this example, it shows the ability to have 1 million fixed height items in a list. +This example showcases Floem's ability to have 1 million fixed height items in a list. -What it does behind the scenes, is effectively only add the list item view on the screen to the view tree, and remove them from the view tree when they are out of view. +Behind the scenes, it is keeping track of the list items that are visible and keeping or adding the items that are in view and removing the view items that are out of view. -The ```VirtualList``` in Floem gives the user a way to deal with really long lists in a performant way without manually doing the adding and removing. \ No newline at end of file +The Floem `VirtualList` gives you a way to deal with extremely long lists in a performant way without manually doing the adding and removing of views from the view tree. diff --git a/examples/widget-gallery/src/main.rs b/examples/widget-gallery/src/main.rs index edc9890d..811be911 100644 --- a/examples/widget-gallery/src/main.rs +++ b/examples/widget-gallery/src/main.rs @@ -25,7 +25,7 @@ use floem::{ style::{Background, CursorStyle, Transition}, unit::{DurationUnitExt, UnitExt}, views::{ - button, h_stack, label, scroll, stack, tab, v_stack, virtual_stack, Decorators, + button, h_stack, label, scroll, stack, tab, v_stack, virtual_stack, Decorators, LabelClass, VirtualDirection, VirtualItemSize, }, window::WindowConfig, @@ -154,7 +154,11 @@ fn app_view() -> impl IntoView { .style(|s| s.flex_col().width(140.0)) }) .scroll_style(|s| s.shrink_to_fit()) - .style(|s| s.border(1.).border_color(Color::GRAY)); + .style(|s| { + s.border(1.) + .border_color(Color::GRAY) + .class(LabelClass, |s| s.selectable(false)) + }); let id = list.id(); let inspector = button("Open Inspector") diff --git a/examples/widget-gallery/src/rich_text.rs b/examples/widget-gallery/src/rich_text.rs index d5855369..86b447a8 100644 --- a/examples/widget-gallery/src/rich_text.rs +++ b/examples/widget-gallery/src/rich_text.rs @@ -3,12 +3,15 @@ use std::ops::Range; use floem::{ peniko::Color, text::{Attrs, AttrsList, Style, TextLayout}, - views::{rich_text, scroll, v_stack, RichTextExt}, + views::{rich_text, scroll, v_stack, Decorators, RichTextExt}, IntoView, }; pub fn rich_text_view() -> impl IntoView { - let builder = "this".red().italic() + " is super cool".blue() + format!("\nnew value: {}", 5); + let builder = "This".red().italic() + + " is easy to build".blue() + + "\nTest value: " + + 5.to_string().green(); let text = " // floem is a ui lib, homepage https://github.com/lapce/floem @@ -17,7 +20,6 @@ pub fn rich_text_view() -> impl IntoView { }"; scroll({ v_stack(( - builder, rich_text(move || { let attrs = Attrs::new().color(Color::BLACK); @@ -86,6 +88,8 @@ pub fn rich_text_view() -> impl IntoView { text_layout.set_text(text, attrs_list); text_layout }), + builder.style(|s| s.padding_left(15)), )) + .style(|s| s.gap(20)) }) } diff --git a/src/lib.rs b/src/lib.rs index 764cabd4..8a652da5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,7 +5,7 @@ //! //! ## Example: Counter //! ```rust -//! use floem::{reactive::*, views::*}; +//! use floem::prelude::*; //! //! let mut counter = RwSignal::new(0); //!