Repository files navigation

It is with great sadness that I announce that OrbTk is sunsetting. In the many years since I first made OrbTk, the Rust GUI ecosystem has grown at an amazing rate. Toolkits with more features have developed, and which are more actively maintained. I first created this project to bootstrap UI development on Redox OS. Many of the applications on Redox use OrbTk.@FloVanGH stepped in to do large refactoring between the 0.2 and 0.3 release, which modernized the OrbTk API.@rzerres stepped in to add many features and maintain OrbTk since the 0.3 release.

I have since moved on to working withiced.@FloVanGH has taken a job working onslint. And@rzerres has expressed interest in usingslint for their projects. Bothiced andslint provide renderer agnostic toolkits that will be compatible with Redox OS, but they also support more features than OrbTk. So, I have decided, with agreement from@rzerres, that OrbTk is to stop being actively maintained, in favor of these other Rust native toolkits.

--Jeremy Soller

The Orbital Widget Toolkit is a cross-platform (G)UI toolkit for building scalable user interfaces with the programming language Rust. It's basedon theEntity Component System Pattern and provides afunctional Reactive-like API.

The main goals of OrbTk are speed, ease of use, and cross-platform compatibility.

The next images are taken from example applications, that have been compiled for MacOS / OS-X.

• Theshowcase example

• Themedcalculator examples

Other screenshots have been rendered fromexamples code, that is storedinside theorbtk crate.

• Modern lightweight API
• Cross platform
• Modular crates
• Based on Entity Component System libraryDCES
• Flexible event system
• Integrated widget library
• Custom widgets
• Custom theming engine
• Dynamic theme switching
• Integrated debugging tools
• Localization

• Redox OS
• Linux
• macOS
• Windows
• openBSD (not tested, but should work)
• Web (broken, will be fixed soon)
• Android (wip, will be released soon)
• iOS (wip, will be released soon)
• Ubuntu Touch (on hold)

• Conformable use of async
• More default widgets
• Book
• Animations
• Split application in modules
• 3D context
• More integrated debugging tools

You can build and view the latest documentation by executing the following command:

cargo doc --no-deps --open

The OrbTk book is written from a developers perspective. It aims tointroduce the basic concept, beside a bird's eye view of the toolkitstructure. An in depth discussion of the provided crates is followedby example listings. This section collects example code with annotatedblocks. The annotations are targeting best practice usage of availablewidgets, their interaction with other modules coupled with adescriptive text where reasonable.

A precompiled version is available foronline reading.You are invited to checkout its repository atOrbTk book.

Please donot expect at finalized version. It is not complete atall. The given statis ismarked as work in progress (WIP). Any help toimprove the chapters and/or translations are quite welcome.

To include OrbTk as an external dependency into your project, add thisline to itsCargo.toml file:

...[dependencies]...orbtk = "0.3.1-alpha4"...

To use the latest development version of OrbTk as an externaldependency, add this line into itsCargo.toml file:

...[dependencies]...orbtk = { git = "https://github.com/redox-os/orbtk.git", branch = "develop" }...

You can also check out the OrbTk template project to start a newproject:https://github.com/redox-os/orbtk-template

use orbtk::prelude::*;fnmain(){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 arethings like Buttons, TextBoxes, ListViews, Views (Screens) andGrid(Layout)s. Each widget implements theWidgettraitand is generated by thewidget!macro. Awidget consists of a name likeButton and a list of its propertiesliketext: String,background: Brush orcount: u32. After thebuild method of a widget is called it's added to the EntityComponent System where it exists as anEntity (index) withComponents. The struct of a widget serves as a builder using thebuilderpattern.

Basic usage of the widget! macro:

widget!(MyWidget{  background:Brush,  count:u32,  text:String,  ...});

Each widget has to implement theTemplatetrait.The template defines the structure and the default values that thewidget will store in its properties. For example: You can define yourhand-craftedButton widget (lets call itMyButton).MyButton isrepresented as a tree of three child widgets: A top levelContainer widget that will hand over to its child, theStackPanelwidget, which in turn will hand over to its child, theTextBlockwidget.

The next code snippet prints out the source code of this basic Template trait:

implTemplateforMyButton{fntemplate(self,id:Entity,ctx:&mutBuildContext) ->Self{self.name("MyButton").style("my_button_style").background("#000000").count(0).text("Initial text").child(Container::new()// Container references the same background as MyButton.background(id).child(TextBlock::new()// TextBlock references the same text as MyButton.text(id).build(ctx)).build(ctx))}}

Any changes that are triggered via user interaction or via events arehandled inside the state of a widget. If generated, they are processedto manipulate the inner state. Each state must implement theStatetrait.The inner state of a widget is represented by the current values ofits properties.

Have a look at this code snippet to make up a state trait:

#[derive(Default,AsAny)]structMyState{...}implStateforMyState{fnupdate(&mutself, _:&mutRegistry,ctx:&mutContext){// update the widget...}}widget!(// Add MyState as state of MyWidgetMyWidget<MyState>{...});

The update method requires aContextparameter.This structure provides access to the state's widget itself (theentity)and its components (theproperties). It also provides methods (theassociated functions) to accessthe children of the widget, this it is able to manipulate the widget tree.

OrbTk provides atheme engine base onRON. The engine provides thefollowing features:

• Split theme in different files
• Reference resources values in the theme files (colors, font stuff)
• Derive styles
• Dynamic theme switching
• State styling (pressed | selected | focused | disabled)

Have a look at this short style definition:

Theme (styles: {"base": (properties: {"font_size":"$FONT_SIZE_12","font_family":"$MEDIUM_FONT",}),"button": (base:"base",properties: {"background":"$BLACK",},states: [(key:"pressed",properties: {"background":"$WHITE",})])},resource: {"BLACK":"#000000","WHITE":"#ffffff","MEDIUM_FONT":"Roboto-Medium","FONT_SIZE_12":12,"FONT_SIZE_16":16,})

But you are not requested to reference a theme engine. OrbTkenables as well the declaraton of property values inside the sourcecode (inlined theming).

OrbTk supports the functionality to register an application widelocalization service. A localization service has to implement theLocalizationtrait.

Example

pubstructMyLocalization{...}implLocalizationforMyLocalization{/// Gets the current language by language key e.g. `en_US` or `de_DE`.fnlanguage(&self) ->&String{...}/// Sets the current language by key e.g. `en_US` or `de_DE`.fnset_language(&mutself,key:&str){...}/// Gets the translated text for the given key. If there is no given translation the `key` will be returned as result.fntext(&self,key:String) ->String{...}}

It is possible to register a localization service for anapplication. Simply make use of theRonLocalization,that can read localization dictionaries coded in theRON format.

Example

let de_de =r#"Dictionary(words: {"hello": "Hallo","world": "Welt",})"#;Application::new().localization(RonLocalization::create()// sets the initial language.language("en_US")// adds an language dictionary to the localization service..dictionary("de_DE", de_de).build()).window(|ctx|{Window::new().title("OrbTk - showcase example").position((100,100)).size(600,730).resizable(true).child(TextBlock::new().text("hello").build(ctx)).build(ctx)}).run();

Inside this example code thetext property (valuehello) is usedas thekey. This key is matched to the correpondingvalue inside thedictionary of the corresponding localization service. If you haven't defined adictionary for the current language, OrbTk will simply take the value of the property itself.You are free to start development without and any localization, but add it afterwards.

You may switch the language at runtime. Inside the state widget you simply consume theset_language method, that is accessible via theContextstructure.

If your target Operating-System isLinux,macOS orWindows, asdl2 installation is required. Please check the documentation thatis provieded for thrust-sdk2 crate.

As an alternative, you may buildOrbTk while bundlingsdl2. To activate thebundled feature go ahead like this:

cargo run --example showcase --features bundled

Please asure, that youtoolchain will provide aworking C compiler (e.g.gcc,clang, or MS's compiler).

To targetlinux, you also need to providecmake:

sudo apt install cmake

If you have trouble build the provided OrbTk examples or simply don't want touse a C compiler, please check the backend section. It containsalternatives.

All example source-code resides inside theexamples subdirectory of the orbtk subcrate.

Compile, start and play around with theshowcase example while executing the following command:

cargo run --example showcase --release

OrbTk has an integrateddebug tools. It will oultline the bounds ofall managed widgets inside the widget tree. This will includeinvisible ones. You may also want to print out the tree structure of your app.This is activated, via feature flags like this:

cargo run --example showcase --release --features "debug, log"

To run the examples as a browser, electron or cordova app you have to install cargo-node:

cargo install -f cargo-node

cargo-node itself relies onnpm version 6.9.0, which is included withNode.js version 10.16.3. You can download itfrom itshomepage.

Rust'scargo is also required. All cargo-node's dependencies are installed automatically.

To start theshowcase example as a node binary, executing one of the following commands:

• Run as browser app:

cargo node run --target browser --example showcase

• Run as electron app:

cargo node run --target electron --example showcase

• Run as cordova app on android:

cargo node run --target android --example showcase

• orbtk: sub-crate, that provides all needed components to build an OrbTkcross platform UI.
• orbtk_core: sub-crate, that provides thecore components of Orbtk (widget basics, tree handling, theming)
• orbtk_orbclient: sub-crate, that handles cross platform awarewindow and event management. It is based onOrbClient.
• orbtk_tinyskia: Wrapper methods that consumes thetiny-skia2D rendering engine.
• orbtk_widgets: sub-crate providing the standard OrbTkwidget library and andtheming support.

• Flutter
• React
• Yew

• Plural Planner: Task app
• Space Editor: 2D Tile Map Editor compatible with OrbGame
• twin-commander: A twin-panel file manager specifically for the Redox OS

If you want to help and improve OrbTk submit your feedback via theissue tracker. All pullrequests are welcome and will be reviewed. You can also discuss withother OrbTk developers via theRedox chatinterface. Please join theorbtkchannel.

• Please document for all yourpub structs, traits and functions.
• Please add suitable tests methods.
• Use static &str for widget ids and new style definitions.
• For widget development check ProgressBar or Slider as an example.
• Add your changes inside CHANGELOG.md
• Extend the example section to show consumption of your code.
• Always runcargo fmt before uploading.
• Please runcargo cippy before uploading.
• Create the PR using our template.

Source-Code is licensed under MIT license (LICENSE).

© 2017-2022 Jeremy Soller
© 2018-2022 Florian Blasius

This documentation work is licensed under aCreative Common License 4.0

© 2020-2022 Ralf Zerres