Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/linebender/xilem
An experimental Rust native UI framework
https://github.com/linebender/xilem
Last synced: 25 days ago
JSON representation
An experimental Rust native UI framework
- Host: GitHub
- URL: https://github.com/linebender/xilem
- Owner: linebender
- License: apache-2.0
- Created: 2022-11-16T21:39:15.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T22:26:18.000Z (7 months ago)
- Last Synced: 2024-04-03T22:27:00.600Z (7 months ago)
- Language: Rust
- Homepage:
- Size: 746 KB
- Stars: 2,642
- Watchers: 74
- Forks: 72
- Open Issues: 36
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rust - xilem - first UI design toolkit [druid](https://github.com/linebender/druid). (Libraries / GUI)
- awesome-2d-graphics-rendering - xilem
- awesome-rust-list - Xilem
- awesome-rust-list - Xilem
README
# Xilem
**An experimental Rust architecture for reactive UI**
[](https://xi.zulipchat.com/#narrow/stream/354396-xilem)
[](https://deps.rs/repo/github/linebender/xilem)
[](#license)
[](https://github.com/linebender/xilem/actions)
[](https://crates.io/crates/xilem)
[](https://docs.rs/xilem)
This repo contains an experimental architecture, implemented with a toy UI. At a very high level, it combines ideas from Flutter, SwiftUI, and Elm. Like all of these, it uses lightweight view objects, diffing them to provide minimal updates to a retained UI. Like SwiftUI, it is strongly typed.
## Community
[](https://xi.zulipchat.com/#narrow/stream/354396-xilem)
Discussion of Xilem development happens in the [Xi Zulip](https://xi.zulipchat.com/), specifically the [#xilem channel](https://xi.zulipchat.com/#narrow/stream/354396-xilem).
All public content can be read without logging in
## Project structure
This diagram gives an idea what the Xilem project is built on:
On a very coarse level, Xilem is built directly on top of xilem_core and Masonry, both of which are crates in this repository.
Then Masonry is built on top of:
- **winit** for window creation.
- **Vello and wgpu** for 2D graphics.
- **Parley** for [the text stack](https://github.com/linebender/parley#the-Parley-text-stack).
- **AccessKit** for plugging into accessibility APIs.
## Architecture
See [ARCHITECTURE.md](./ARCHITECTURE.md) for details.
### Overall program flow
> **Warning:**
>
> This README is a bit out of date. To understand more of what's going on, please read the blog post, [Xilem: an architecture for UI in Rust].
Like Elm, the app logic contains *centralized state.* On each cycle (meaning, roughly, on each high-level UI interaction such as a button click), the framework calls a closure, giving it mutable access to the app state, and the return value is a *view tree.* This view tree is fairly short-lived; it is used to render the UI, possibly dispatch some events, and be used as a reference for *diffing* by the next cycle, at which point it is dropped.
We'll use the standard counter example. Here the state is a single integer, and the view tree is a column containing two buttons.
```rust
fn app_logic(data: &mut u32) -> impl View {
Column::new((
Button::new(format!("count: {}", data), |data| *data += 1),
Button::new("reset", |data| *data = 0),
))
}
```
These are all just vanilla data structures. The next step is diffing or reconciling against a previous version, now a standard technique. The result is an *element tree.* Each node type in the view tree has a corresponding element as an associated type. The `build` method on a view node creates the element, and the `rebuild` method diffs against the previous version (for example, if the string changes) and updates the element. There's also an associated state tree, not actually needed in this simple example, but would be used for memoization.
The closures are the interesting part. When they're run, they take a mutable reference to the app data.
### Components
A major goal is to support React-like components, where modules that build UI for some fragment of the overall app state are composed together.
```rust
struct AppData {
count: u32,
}
fn count_button(count: u32) -> impl View {
Button::new(format!("count: {}", count), |data| *data += 1)
}
fn app_logic(data: &mut AppData) -> impl View {
Adapt::new(|data: &mut AppData, thunk| thunk.call(&mut data.count),
count_button(data.count))
}
```
This adapt node is very similar to a lens (quite familiar to existing Druid users), and is also very similar to the [Html.map] node in Elm. Note that in this case the data presented to the child component to render, and the mutable app state available in callbacks is the same, but that is not necessarily the case.
### Memoization
In the simplest case, the app builds the entire view tree, which is diffed against the previous tree, only to find that most of it hasn't changed.
When a subtree is a pure function of some data, as is the case for the button above, it makes sense to *memoize.* The data is compared to the previous version, and only when it's changed is the view tree build. The signature of the memoize node is nearly identical to [Html.lazy] in Elm:
```rust
fn app_logic(data: &mut AppData) -> impl View {
Memoize::new(data.count, |count| {
Button::new(format!("count: {}", count), |data: &mut AppData| {
data.count += 1
})
}),
}
```
The current code uses a `PartialEq` bound, but in practice I think it might be much more useful to use pointer equality on `Rc` and `Arc`.
The combination of memoization with pointer equality and an adapt node that calls [Rc::make_mut] on the parent type is actually a powerful form of change tracking, similar in scope to Adapton, self-adjusting computation, or the types of binding objects used in SwiftUI. If a piece of data is rendered in two different places, it automatically propagates the change to both of those, without having to do any explicit management of the dependency graph.
I anticipate it will also be possible to do dirty tracking manually - the app logic can set a dirty flag when a subtree needs re-rendering.
### Optional type erasure
By default, view nodes are strongly typed. The type of a container includes the types of its children (through the `ViewTuple` trait), so for a large tree the type can become quite large. In addition, such types don't make for easy dynamic reconfiguration of the UI. SwiftUI has exactly this issue, and provides [AnyView] as the solution. Ours is more or less identical.
The type erasure of View nodes is not an easy trick, as the trait has two associated types and the `rebuild` method takes the previous view as a `&Self` typed parameter. Nonetheless, it is possible. (As far as I know, Olivier Faure was the first to demonstrate this technique, in [Panoramix], but I'm happy to be further enlightened)
## Prerequisites
### Linux and BSD
You need to have installed `pkg-config`, `clang`, and the development packages of `wayland`,
`libxkbcommon`, `libxcb`, and `vulkan-loader`. Most distributions have `pkg-config` installed by default.
To install the remaining packages on Fedora, run:
```sh
sudo dnf install clang wayland-devel libxkbcommon-x11-devel libxcb-devel vulkan-loader-devel
```
To install the remaining packages on Debian or Ubuntu, run:
```sh
sudo apt-get install clang libwayland-dev libxkbcommon-x11-dev libvulkan-dev
```
## Minimum supported Rust Version (MSRV)
This version of Xilem has been verified to compile with **Rust 1.79** and later.
Future versions of Xilem might increase the Rust version requirement.
It will not be treated as a breaking change and as such can even happen with small patch releases.
Click here if compiling fails.
As time has passed, some of Xilem's dependencies could have released versions with a higher Rust requirement.
If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.
```sh
# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1
```
## License
Licensed under the Apache License, Version 2.0
([LICENSE](LICENSE) or )
Some files used for examples are under different licenses:
- The font file (`RobotoFlex-Subset.ttf`) in `xilem/resources/fonts/roboto_flex/` is licensed solely as documented in that folder (and is not licensed under the Apache License, Version 2.0).
- The data file (`status.csv`) in `xilem/resources/data/http_cats_status/` is licensed solely as documented in that folder (and is not licensed under the Apache License, Version 2.0).
## Contribution
Contributions are welcome by pull request. The [Rust code of conduct] applies.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
licensed as above, without any additional terms or conditions.
[Html.lazy]: https://guide.elm-lang.org/optimization/lazy.html
[Html map]: https://package.elm-lang.org/packages/elm/html/latest/Html#map
[Rc::make_mut]: https://doc.rust-lang.org/std/rc/struct.Rc.html#method.make_mut
[AnyView]: https://developer.apple.com/documentation/swiftui/anyview
[Panoramix]: https://github.com/PoignardAzur/panoramix
[Xilem: an architecture for UI in Rust]: https://raphlinus.github.io/rust/gui/2022/05/07/ui-architecture.html
[xkbcommon]: https://github.com/xkbcommon/libxkbcommon
[rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct