The Orbital Widget Toolkit is a cross-platform (G)UI toolkit for building scalable user interfaces with the programming language Rust. It's based on the Entity Component System Pattern and provides a functional Reactive-like API.
The main goals of OrbTk are speed, ease of use, and cross-platform compatibility.
To include OrbTk in your project, add this dependency
line to your Cargo.toml file:
text
orbtk = "0.3.1-alpha3"
To use the latest development version of OrbTk, add this dependency
line to your Cargo.toml file:
text
orbtk = { git = "https://github.com/redox-os/orbtk.git", branch = "develop" }
You can also check out the OrbTk template project to start a new project: https://github.com/redox-os/orbtk-template.
```rust use orbtk::prelude::*;
fn main() { Application::new() .window(|ctx| { Window::new() .title("OrbTk - minimal example") .position((100.0, 100.0)) .size(420.0, 730.0) .child(TextBlock::new().text("OrbTk").build(ctx)) .build(ctx) }) .run(); } ```
Widgets are the building blocks of user interfaces in OrbTk. They are things like Buttons, TextBoxes, ListViews, Views (Screens) and Grid(Layout)s. Each widget implements the Widget trait and is generated by the widget! macro. A widget consists of a name like Button and a list of its properties like text: String16, background: Brush or count: u32. After the build method of a widget is called it's added to the Entity Component System where it exists as an Entity (index) with Components. The struct of a widget serves as a builder using the builder pattern.
Basic usage of the widget! macro:
rust
widget!(
MyWidget {
background: Brush,
count: u32,
text: String16,
...
}
);
Each widget has to implement the Template trait. The template defines the default values of a widget's properties as well as its structure. A
Button e.g. consists of a Container widget, a StackPanel widget and a TextBlock widget.
Basic usage of the Template trait:
rust
impl Template for MyWidget {
fn template(self, id: Entity, ctx: &mut BuildContext) -> Self {
self.name("MyWidget")
.style("my_widget_style")
.background("#000000")
.count(0)
.text("Initial text")
.child(Container::new()
// Container references the same background as MyWidget
.background(id)
.child(TextBlock::new()
// TextBlock references the same text as MyWidget
.text(id)
.build(ctx)
)
.build(ctx)
)
}
}
The state of a widget is used to update its inner state. Each state has to implement the State trait. The inner state of a widget is represented by the current values of its properties.
Basic usage of the state trait:
```rust
struct MyState { ... }
impl State for MyState { fn update(&mut self, _: &mut Registry, ctx: &mut Context) { // update the widget ... } }
widget!(
// Add MyState as state of MyWidget
MyWidget
The Context parameter of the update method provides access to the state's widget (entity) and its properties (components). It also provides functions to access the children of the widget, and to manipulate the widget tree.
OrbTk provides a theme engine base on RON. The engine provides the following features:
Short example:
ron
Theme (
styles: {
"base": (
properties: {
"font_size": "$FONT_SIZE_12",
"font_family": "$MEDIUM_FONT",
}
),
"button": (
base: "base",
properties: {
"background": "$BLACK",
},
states: {
"pressed": {
"background": "$WHITE",
}
}
)
},
resource: {
"BLACK": "#000000",
"WHITE": "#ffffff",
"MEDIUM_FONT": "Roboto-Medium",
"FONT_SIZE_12": 12,
"FONT_SIZE_16": 16,
}
)
OrbTk will also provide a plain mechanism to style and theme widgets and UIs.
On Linux you first need to install
shell
sudo apt install libxkbcommon-dev libwayland-cursor0 libwayland-dev
You can find examples in the examples/ directory.
You can start the widgets example by executing the following command:
text
cargo run --example widgets --release
OrbTk has integrated debug tools. If you want to show the bounds of all widgets (even invisible ones) and want to see a debug print of the whole widget tree, you can run the examples with --features debug, like this:
text
cargo run --example widgets --release --features debug
To run the examples as a browser, electron or cordova app you have to install cargo-node:
text
cargo install -f cargo-node
Before you can use cargo-node you have to install npm version 6.9.0, which is included with Node.js version 10.16.3. You can download it from https://nodejs.org/dist/v10.16.3/.
Rust's cargo is also required. The rest of cargo-node's dependencies are installed automatically.
You can run the "widgets" example by executing one of the following commands:
text
cargo node run --target browser --example widgets
text
cargo node run --target electron --example widgets
text
cargo node run --target android --example widgets
You can build and view the latest documentation by executing the following command:
text
cargo doc --no-deps --open
To build and run the latest version of the OrbTk manual check: Manual
If you want to help improve OrbTk you submit your feedback in the issue tracker, or make a pull request to fix an issue https://github.com/redox-os/orbtk/issues. You can also discuss OrbTk with us on the Redox chat https://redox-os.org/community/ (join the OrbTk channel).
pub structs, traits and funscargo fmt add the endLicensed under MIT license (LICENSE).