README.md 4.97 KB
Newer Older
1
<img alt="OrbTk" width="380" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/logos/orbtk/logo_dark.png">
Jeremy Soller's avatar
Jeremy Soller committed
2

Florian Blasius's avatar
Florian Blasius committed
3
[![Build status](https://gitlab.redox-os.org/redox-os/orbtk/badges/master/build.svg)](https://gitlab.redox-os.org/redox-os/orbtk/pipelines)
Jeremy Soller's avatar
Jeremy Soller committed
4
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
Florian Blasius's avatar
Florian Blasius committed
5
[![crates.io](https://img.shields.io/badge/crates.io-v0.2.27-orange.svg)](https://crates.io/crates/orbtk)
Jeremy Soller's avatar
Jeremy Soller committed
6
[![docs.rs](https://docs.rs/orbtk/badge.svg)](https://docs.rs/orbtk)
7

8
9
> OrbTk 0.3.0 is under heavy development and it's not compatible to earlier releases.

Florian Blasius's avatar
Florian Blasius committed
10
The Orbital Widget Toolkit is a multi platform (G)UI toolkit for building scalable user interfaces with the programming language Rust. It's based
11
on the [Entity Component System Pattern](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) and provides a functional-reactive like API. 
12

13
The main goals of OrbTk are fast performance, easy to use and cross platform.
14

15
<img alt="Calculator" width="350" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/Calculator.png">
Florian Blasius's avatar
Florian Blasius committed
16

Florian Blasius's avatar
Florian Blasius committed
17
18
## Features:

19
* Modern lightweight API
Florian Blasius's avatar
Florian Blasius committed
20
* Uses the Entity Component System library [DCES](https://gitlab.redox-os.org/redox-os/dces-rust) for widget and properties handling
21
* Updating instead of rebuilding sub-trees
Florian Blasius's avatar
Florian Blasius committed
22
23
* Flexible event system
* Widget state management
24
* Cross platform: Redox OS, Linux, macOS, Windows
25
* CSS theming
Florian Blasius's avatar
Florian Blasius committed
26

27
28
## Usage

Florian Blasius's avatar
Florian Blasius committed
29
To include OrbTk in your project, just add the dependency
30
31
32
line to your `Cargo.toml` file:

```text
Florian Blasius's avatar
Florian Blasius committed
33
orbtk = "0.2.27"
34
35
```

Florian Blasius's avatar
Florian Blasius committed
36
To use OrbTk 0.3, just add the dependency
Florian Blasius's avatar
Florian Blasius committed
37
38
39
line to your `Cargo.toml` file:

```text
Florian Blasius's avatar
Florian Blasius committed
40
orbtk = { git = "https://gitlab.redox-os.org/redox-os/orbtk.git" }
Florian Blasius's avatar
Florian Blasius committed
41
42
```

43
44
45
46
However you also need to have the SDL2 libraries installed on your
system.  The best way to do this is documented [by the SDL2
crate](https://github.com/AngryLawyer/rust-sdl2#user-content-requirements).

Florian Blasius's avatar
Florian Blasius committed
47
48
49
50
51
52
53
54
## Use OrbTk with cairo

If you want to use OrbTk with cairo (recommanded) you have to install cairo graphics. Otherwise you have to build OrbTk with the "plain" feature.

* With Ubuntu, please to type ```sudo apt-get install libcairo2-dev``` in your console.
* With macOS and homebrew, please to type ```brew install cairo``` in your console.
* With macOS and macports, please to type ```sudo port install cairo``` in your console.

55
56
57
## Minimal Example

```rust
58
use orbtk::prelude::*;
59
60

fn main() {
61
62
63
64
65
66
67
68
69
70
      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();
71
72
}
```
Keith Wade's avatar
Keith Wade committed
73

74
## Additional Examples
75
76
77

You find the examples in the `examples/` directory.

Florian Blasius's avatar
Florian Blasius committed
78
You can start the widgets example by executing the following command:
79
80

```text
81
82
83
cargo run --example widgets --release
```

84
85
86
87
88
89
90
91
## Additional Examples on Web

To run the examples on a browser you have to install 

```text
cargo install -f cargo-web
```

Florian Blasius's avatar
Florian Blasius committed
92
### Run
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

You can start the widgets example by executing the following command:

* Compile to [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly) using Rust's native WebAssembly backend:

```text
cargo web start --target=wasm32-unknown-unknown --auto-reload --example widgets
```

* Compile to [asm.js](https://en.wikipedia.org/wiki/Asm.js) using Emscripten:

```text
$ cargo web start --target=asmjs-unknown-emscripten --auto-reload --example widgets
```

* Compile to WebAssembly using Emscripten:

```text
$ cargo web start --target=wasm32-unknown-emscripten --auto-reload --example widgets
```

114
## Build and run documentation
115
116
117
118
119

You can build and run the latest documentation y executing the following command:

```text
cargo doc --no-deps --open
Keith Wade's avatar
Keith Wade committed
120
```
Keith Wade's avatar
Keith Wade committed
121

122
## Planned features
Florian Blasius's avatar
Florian Blasius committed
123
124
125
126
127
128
129
130
131

* Style guide
* More default widgets
* More examples
* Book
* Animations
* Exchange views / widgets / screens on runtime
* Split application in modules
* Theme update
132
* Support for Android, iOS, Ubuntu Touch and WebAssembly
Florian Blasius's avatar
Florian Blasius committed
133
* Vulkan / OpenGL Support 
Florian Blasius's avatar
Florian Blasius committed
134

Florian Blasius's avatar
Florian Blasius committed
135
136
137
138
139
140
141
142
143
144
## Sub Crates

* api: base api elements of OrbTk e.g. widget and application parts
* css-engine: parse and read values from a css file
* shell: cross platform window and event handling
* theme: OrbTk's default theme (light and dark)
* tree: Tree structure based on DCES
* utils: Helper structs and traits
* widgets: Base widget library

145
146
## Dependencies

147
148
* [OrbGL](https://gitlab.redox-os.org/redox-os/orbgl): 2D/3D drawing
* [OrbClient](https://gitlab.redox-os.org/redox-os/orbclient): window creation, window events
149
150
151
152
153
* [OrbFont](https://gitlab.redox-os.org/redox-os/orbfont): font rendering
* [OrbImage](https://gitlab.redox-os.org/redox-os/orbimage/tree/master/src): image loading
* [DCES](https://gitlab.redox-os.org/redox-os/dces-rust): Entity Component System
* [rust-cssparser](https://github.com/servo/rust-cssparser): CSS parsing

Florian Blasius's avatar
Florian Blasius committed
154
155
156
157
158
159
## Inspirations

* [Flutter](https://flutter.io/)
* [React](https://reactjs.org/)
* [Yew](https://github.com/DenisKolodin/yew)