# orbtk
**Repository Path**: mashiro_chen/orbtk
## Basic Information
- **Project Name**: orbtk
- **Description**: The Rust UI-Toolkit.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-04
- **Last Updated**: 2020-12-20
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[](https://github.com/redox-os/orbtk/actions)
[](./LICENSE)
[](https://crates.io/crates/orbtk/0.3.1-alpha1)
[](https://docs.rs/orbtk)
The Orbital Widget Toolkit is a multi platform (G)UI toolkit for building scalable user interfaces with the programming language Rust. It's based
on the [Entity Component System Pattern](https://en.wikipedia.org/wiki/Entity_component_system) and provides a functional-reactive like API.
The main goals of OrbTk are speed, ease of use, and being cross platform.
## Features:
* Modern lightweight API
* Cross platform
* Modular crates
* Based on Entity Component System library [DCES](https://gitlab.redox-os.org/redox-os/dces-rust)
* Flexible event system
* Integrated widget library
* Custom widgets
* Theming
* Integrated debugging tools
## Platforms
* Redox OS (native | cargo-node)
* Linux (native | cargo-node)
* macOS (native | cargo-node)
* Windows (native | cargo-node)
* openBSD (not tested, but should work)
* Web (cargo-node)
* Android (native planned after 0.3 | cargo-node)
* iOS (native planned after 0.3 | cargo-node planned after 0.3)
* Ubuntu Touch (native planned after 0.3 | cargo-node planned for 0.3)
## Planned features
* Conformable use of async
* More default widgets
* More examples
* Book
* Animations
* Split application in modules
* Theme update
* 3D context
* More integrated debugging tools
## Usage
To include OrbTk in your project, just add the dependency
line to your `Cargo.toml` file:
```text
orbtk = "0.3.1-alpha1"
```
To use the latest development version of OrbTk, just add the dependency
line to your `Cargo.toml` file:
```text
orbtk = { git = "https://github.com/redox-os/orbtk.git", branch = "develop" }
```
You could also check out the OrbTk template project to start a new project: https://github.com/redox-os/orbtk-template.
## Minimal Example
```rust
use orbtk::prelude::*;
fn main() {
Application::new()
.window(|ctx| {
Window::create()
.title("OrbTk - minimal example")
.position((100.0, 100.0))
.size(420.0, 730.0)
.child(TextBlock::create().text("OrbTk").build(ctx))
.build(ctx)
})
.run();
}
```
## Base concepts
### Widget
Widgets are the building blocks of user interfaces created with OrbTk like Buttons, TextBoxes, ListViews, Views (Screens) and Grid(Layout)s. Each widget does implement the [Widget trait](https://github.com/redox-os/orbtk/blob/develop/crates/api/src/widget/mod.rs) and is generated by the [widget! macro](https://github.com/redox-os/orbtk/blob/develop/crates/api/src/macros.rs). 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, the widget exists as `Entity` (index) and its properties as `Components` in the Entity Component System. The struct of a widget serves itself as builder.
Base usage of the widget! macro:
```rust
widget!(
MyWidget {
background: Brush,
count: u32,
text: String16,
...
}
);
```
### Widget Templates
Each widget has to implement the [Template trait](https://github.com/redox-os/orbtk/blob/develop/crates/api/src/widget/template.rs). A template is used to define the default property values of a widget and to define its structure. A
Button e.g. consists of a `Container` widget, a `StackPanel` widget and a `TextBlock` widget.
Base usage of the Template trait:
```rust
impl Template for MyWidget {
fn template(self, id: Entity, ctx: &mut BuildContext) -> Self {
self.name("MyWidget")
.background("#000000")
.count(0)
.text("Initial text")
.child(
Container::create()
// Container references the same background as MyWidget
.background(id)
.child(
TextBlock::create()
// TextBlock references the same text as MyWidget
.text(id)
.build(ctx)
)
.build(ctx)
)
}
}
```
### Widget State
The state of a widget is used to update its inner state. Each state has to implement the [State trait](https://github.com/redox-os/orbtk/blob/develop/crates/api/src/widget/state.rs). The inner state of a widget is represented by the
current values of its properties.
Base usage of the state trait:
```rust
#[derive(Default, AsAny)]
struct MyWidgetState {
...
}
impl State for MyWidgetState {
fn update(&mut self, _: &mut Registry, ctx: &mut Context<'_>) {
// update the widget
...
}
}
widget!(
// Add MyState as state of MyWidget
MyWidget {
...
}
);
```
The [Context parameter](https://github.com/redox-os/orbtk/blob/develop/crates/api/src/widget/context.rs) of the update method give you access the states widget (entity) and its properties (components). It also provides functions to access the children of the widget and functions to manipulate the widget tree.
## Run Examples
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 also an integrated `debug` tools. If you want to show the bounds of all widgets (also non visual widgets) and want to see a debug print of the whole widget
tree you could run the examples as follows:
```text
cargo run --example widgets --release --features debug
```
## Run Examples with cargo-node
To run the examples on as browser, electron or cordova app you have to install
```text
cargo install -f cargo-node
```
Before you could use cargo node you have to install `npm` version 6.9.0. It is included in the `Node.js` version 10.16.3. You could download it from https://nodejs.org/dist/v10.16.3/.
Rust's `cargo` is presumed. All other dependencies of cargo node will be installed automatic.
### Start examples
You can start the widgets example by executing the following command:
* Run as browser app:
```text
cargo node run --target browser --example widgets
```
* Run as electron app:
```text
cargo node run --target electron --example widgets
```
* Run as cordova app on android:
```text
cargo node run --target android --example widgets
```
## Build and run documentation
You can build and run the latest documentation by executing the following command:
```text
cargo doc --no-deps --open
```
## Sub Crates
* [api](https://github.com/redox-os/orbtk/tree/develop/crates/api): base api elements of OrbTk e.g. widget and application parts
* [css-engine](https://github.com/redox-os/orbtk/tree/develop/crates/css-engine): parse and read values from a css file
* [proc-macros](https://github.com/redox-os/orbtk/tree/develop/crates/proc-macros): procedural helper macros
* [render](https://github.com/redox-os/orbtk/tree/develop/crates/render): cross platform 2D/3D render library
* [shell](https://github.com/redox-os/orbtk/tree/develop/crates/api): cross platform window and event handling
* [theme](https://github.com/redox-os/orbtk/tree/develop/crates/theme): OrbTks default theme (light and dark)
* [tree](https://github.com/redox-os/orbtk/tree/develop/crates/tree): tree structure based on DCES
* [utils](https://github.com/redox-os/orbtk/tree/develop/crates/utils): helper structs and traits
* [widgets](https://github.com/redox-os/orbtk/tree/develop/crates/widgets): base widget library
## Inspirations
* [Flutter](https://flutter.io/)
* [React](https://reactjs.org/)
* [Yew](https://github.com/DenisKolodin/yew)
## Showcases
* [Space Editor](https://codeberg.org/flovanco/space-editor): 2D Tile Map Editor compatible with OrbGame
* [doit](https://codeberg.org/flovanco/doit): Task app
* [OrbCalculator](https://gitlab.redox-os.org/redox-os/orbcalculator): Calculator based on OrbTk
## Contribution
If you want to help bring OrbTk further or you have feedback check our issues https://github.com/redox-os/orbtk/issues. You could also discuss with us about OrbTk on the Redox chat https://redox-os.org/community/ (join the OrbTk channel).
## License
Licensed under MIT license ([LICENSE](LICENSE)).