{"id":13440358,"url":"https://github.com/redox-os/orbtk","last_synced_at":"2025-05-13T21:12:01.585Z","repository":{"id":37678084,"uuid":"47995932","full_name":"redox-os/orbtk","owner":"redox-os","description":"The Rust UI-Toolkit.","archived":false,"fork":false,"pushed_at":"2022-10-18T07:27:31.000Z","size":17065,"stargazers_count":3789,"open_issues_count":88,"forks_count":187,"subscribers_count":75,"default_branch":"develop","last_synced_at":"2025-04-28T17:05:04.983Z","etag":null,"topics":["cross-platform","entity-component","gui","redox-os","rust","rust-lang","widgets"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redox-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-14T19:17:13.000Z","updated_at":"2025-04-28T12:52:29.000Z","dependencies_parsed_at":"2022-07-12T16:43:00.727Z","dependency_job_id":null,"html_url":"https://github.com/redox-os/orbtk","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redox-os%2Forbtk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redox-os%2Forbtk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redox-os%2Forbtk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redox-os%2Forbtk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redox-os","download_url":"https://codeload.github.com/redox-os/orbtk/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254029005,"owners_count":22002283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","entity-component","gui","redox-os","rust","rust-lang","widgets"],"created_at":"2024-07-31T03:01:22.025Z","updated_at":"2025-05-13T21:11:56.569Z","avatar_url":"https://github.com/redox-os.png","language":"Rust","readme":"## OrbTk is Sunsetting\n\nIt 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](https://github.com/FloVanGH) stepped in to do large refactoring between the 0.2 and 0.3 release, which modernized the OrbTk API. [@rzerres](https://github.com/rzerres) stepped in to add many features and maintain OrbTk since the 0.3 release.\n\nI have since moved on to working with [iced](https://iced.rs/). [@FloVanGH](https://github.com/FloVanGH) has taken a job working on [slint](https://slint-ui.com/). And [@rzerres](https://github.com/rzerres) has expressed interest in using [slint](https://slint-ui.com/) for their projects. Both [iced](https://iced.rs/) and [slint](https://slint-ui.com/) 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](https://github.com/rzerres), that OrbTk is to stop being actively maintained, in favor of these other Rust native toolkits.\n\n-- [Jeremy Soller](https://github.com/jackpot51/)\n\n## Original README\n\n\u003cimg alt=\"OrbTk\" width=\"380\" src=\"https://raw.githubusercontent.com/redox-os/orbtk/develop/orbtk/images/orbtk_logo_dark.png\"\u003e\n\n[![Build and test](https://github.com/redox-os/orbtk/workflows/CI/badge.svg)](https://github.com/redox-os/orbtk/actions)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![crates.io](https://img.shields.io/badge/crates.io-0.3.1alpha4-orange.svg)](https://crates.io/crates/orbtk/0.3.1-alpha4)\n[![docs.rs](https://img.shields.io/badge/docs-0.3.1alpha4-blue.svg)](https://docs.rs/crate/orbtk/0.3.1-alpha4)\n\nThe Orbital Widget Toolkit is a cross-platform (G)UI toolkit for building scalable user interfaces with the programming language Rust. It's based\non the [Entity Component System Pattern](https://en.wikipedia.org/wiki/Entity_component_system) and provides a [functional Reactive](https://en.wikipedia.org/wiki/Functional_reactive_programming)-like API.\n\nThe main goals of OrbTk are speed, ease of use, and cross-platform compatibility.\n\n## Screenshots\n\nThe next images are taken from example applications, that have been compiled for MacOS / OS-X.\n\n* The `showcase` example\n\n\u003cimg alt=\"showcase\" src=\"https://raw.githubusercontent.com/redox-os/orbtk/develop/orbtk/screenshots/showcase_button_macos.png\"\u003e\n\n* Themed `calculator` examples\n\n\u003cp float=\"left\"\u003e\n\u003cimg alt=\"calculator_dark_macos\" height=\"300\" src=\"https://raw.githubusercontent.com/redox-os/orbtk/develop/orbtk/screenshots/calculator_dark_macos.png\"\u003e\n\u003cimg alt=\"calculator_light_macos\" height=\"300\" src=\"https://raw.githubusercontent.com/redox-os/orbtk/develop/orbtk/screenshots/calculator_light_macos.png\"\u003e\n\u003cimg alt=\"calculator_redox\" height=\"300\" src=\"https://raw.githubusercontent.com/redox-os/orbtk/develop/orbtk/screenshots/calculator_redox.png\"\u003e\n\u003c/p\u003e\n\nOther screenshots have been rendered from [examples code](https://github.com/redox-os/orbtk/blob/develop/orbtk/examples/README.md), that is stored\ninside the `orbtk` crate.\n\n## Features:\n\n* Modern lightweight API\n* Cross platform\n* Modular crates\n* Based on Entity Component System library [DCES](https://gitlab.redox-os.org/redox-os/dces-rust)\n* Flexible event system\n* Integrated widget library\n* Custom widgets\n* Custom theming engine\n* Dynamic theme switching\n* Integrated debugging tools\n* Localization\n\n## Platforms\n\n* Redox OS\n* Linux\n* macOS\n* Windows\n* openBSD (not tested, but should work)\n* Web (broken, will be fixed soon)\n* Android (wip, will be released soon)\n* iOS (wip, will be released soon)\n* Ubuntu Touch (on hold)\n\n## Planned features\n\n* Conformable use of async\n* More default widgets\n* Book\n* Animations\n* Split application in modules\n* 3D context\n* More integrated debugging tools\n\n## Documentation\n\n### Build and open documentation\n\nYou can build and view the latest documentation by executing the following command:\n\n```text\ncargo doc --no-deps --open\n```\n\n### OrbTk book\n\nThe OrbTk book is written from a developers perspective. It aims to\nintroduce the basic concept, beside a bird's eye view of the toolkit\nstructure. An in depth discussion of the provided crates is followed\nby example listings. This section collects example code with annotated\nblocks. The annotations are targeting best practice usage of available\nwidgets, their interaction with other modules coupled with a\ndescriptive text where reasonable.\n\nA precompiled version is available for [online](https://github.com/redox-os/orbtk-book/wiki) reading.\nYou are invited to checkout its repository at [OrbTk book](https://github.com/redox-os/orbtk-book).\n\nPlease do **not** expect at finalized version. It is not complete at\nall. The given statis is `marked as work in progress` (WIP). Any help to\nimprove the chapters and/or translations are quite welcome.\n\n## Usage\n\nTo include OrbTk as an external dependency into your project, add this\nline to its `Cargo.toml` file:\n\n```text\n...\n[dependencies]\n...\norbtk = \"0.3.1-alpha4\"\n...\n```\n\nTo use the latest development version of OrbTk as an external\ndependency, add this line into its `Cargo.toml` file:\n\n```text\n...\n[dependencies]\n...\norbtk = { git = \"https://github.com/redox-os/orbtk.git\", branch = \"develop\" }\n...\n```\n\nYou can also check out the OrbTk template project to start a new\nproject: https://github.com/redox-os/orbtk-template\n\n## Minimal Example\n\n```rust\nuse orbtk::prelude::*;\n\nfn main() {\n\t  Application::new()\n\t\t.window(|ctx| {\n\t\t\tWindow::new()\n\t\t\t\t.title(\"OrbTk - minimal example\")\n\t\t\t\t.position((100.0, 100.0))\n\t\t\t\t.size(420.0, 730.0)\n\t\t\t\t.child(TextBlock::new().text(\"OrbTk\").build(ctx))\n\t\t\t\t.build(ctx)\n\t\t})\n\t\t.run();\n}\n```\n\n## Base concepts\n\n### Widget\n\nWidgets are the building blocks of user interfaces in OrbTk. They are\nthings like Buttons, TextBoxes, ListViews, Views (Screens) and\nGrid(Layout)s. Each widget implements the [Widget\ntrait](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/widget_base/mod.rs)\nand is generated by the [widget!\nmacro](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/macros.rs). A\nwidget consists of a name like `Button` and a list of its properties\nlike `text: String`, `background: Brush` or `count: u32`. After the\n`build` method of a widget is called it's added to the Entity\nComponent System where it exists as an `Entity` (index) with\n`Components`. The struct of a widget serves as a builder using the\n[builder\npattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html).\n\nBasic usage of the widget! macro:\n\n```rust\nwidget!(\n\tMyWidget {\n\t  background: Brush,\n\t  count: u32,\n\t  text: String,\n\t  ...\n\t}\n);\n```\n\n### Widget Templates\n\nEach widget has to implement the [Template\ntrait](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/widget_base/template.rs).\nThe template defines the structure and the default values that the\nwidget will store in its properties. For example: You can define your\nhand-crafted `Button` widget (lets call it `MyButton`). `MyButton` is\nrepresented as a tree of three child widgets: A top level\n`Container` widget that will hand over to its child, the `StackPanel`\nwidget, which in turn will hand over to its child, the `TextBlock`\nwidget.\n\nThe next code snippet prints out the source code of this basic Template trait:\n\n```rust\nimpl Template for MyButton {\n\tfn template(self, id: Entity, ctx: \u0026mut BuildContext) -\u003e Self {\n\t\t self.name(\"MyButton\")\n\t\t\t.style(\"my_button_style\")\n\t\t\t.background(\"#000000\")\n\t\t\t.count(0)\n\t\t\t.text(\"Initial text\")\n\t\t\t.child(Container::new()\n\t\t\t\t\t// Container references the same background as MyButton\n\t\t\t\t\t.background(id)\n\t\t\t\t\t.child(TextBlock::new()\n\t\t\t\t\t\t\t// TextBlock references the same text as MyButton\n\t\t\t\t\t\t\t.text(id)\n\t\t\t\t\t\t\t.build(ctx)\n\t\t\t\t\t)\n\t\t\t\t\t.build(ctx)\n\t\t\t)\n\t}\n}\n```\n\n### Widget State\n\nAny changes that are triggered via user interaction or via events are\nhandled inside the state of a widget. If generated, they are processed\nto manipulate the inner state. Each state must implement the [State\ntrait](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/widget_base/state.rs).\nThe inner state of a widget is represented by the current values of\nits properties.\n\nHave a look at this code snippet to make up a state trait:\n\n```rust\n#[derive(Default, AsAny)]\nstruct MyState {\n\t...\n}\n\nimpl State for MyState {\n\tfn update(\u0026mut self, _: \u0026mut Registry, ctx: \u0026mut Context) {\n\t\t// update the widget\n\t\t...\n\t}\n}\n\nwidget!(\n\t// Add MyState as state of MyWidget\n\tMyWidget\u003cMyState\u003e {\n\t\t...\n\t}\n);\n```\n\nThe update method requires a [`Context`\nparameter](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/widget_base/context.rs).\nThis structure provides access to the state's widget itself (the `entity`)\nand its components (the `properties`). It also provides methods (the `associated functions`) to access\nthe children of the widget, this it is able to manipulate the widget tree.\n\n### Styling widgets and define themes\n\nOrbTk provides a `theme engine` base on\n[RON](https://github.com/ron-rs/ron). The engine provides the\nfollowing features:\n\n* Split theme in different files\n* Reference resources values in the theme files (colors, font stuff)\n* Derive styles\n* Dynamic theme switching\n* State styling (pressed | selected | focused | disabled)\n\nHave a look at this short style definition:\n\n```ron\nTheme (\n\tstyles: {\n\t\t\"base\": (\n\t\t\tproperties: {\n\t\t\t\t\"font_size\": \"$FONT_SIZE_12\",\n\t\t\t\t\"font_family\": \"$MEDIUM_FONT\",\n\t\t\t}\n\t\t),\n\t\t\"button\": (\n\t\t\tbase: \"base\",\n\t\t\tproperties: {\n\t\t\t\t\"background\": \"$BLACK\",\n\t\t\t},\n\t\t\tstates: [\n\t\t\t\t(\n\t\t\t\t\tkey: \"pressed\",\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\t\"background\": \"$WHITE\",\n\t\t\t\t\t}\n\t\t\t\t)\n\t\t\t]\n\t\t)\n\t},\n\tresource: {\n\t\t\"BLACK\": \"#000000\",\n\t\t\"WHITE\": \"#ffffff\",\n\t\t\"MEDIUM_FONT\": \"Roboto-Medium\",\n\t\t\"FONT_SIZE_12\": 12,\n\t\t\"FONT_SIZE_16\": 16,\n\t}\n)\n```\n\nBut you are not requested to reference a theme engine. OrbTk\nenables as well the declaraton of property values inside the source\ncode (`inlined theming`).\n\n### Localization\n\nOrbTk supports the functionality to register an application wide\nlocalization service. A localization service has to implement the\n[Localization](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/localization/mod.rs)\ntrait.\n\n*Example*\n\n```rust\npub struct MyLocalization {\n\t...\n}\n\nimpl Localization for MyLocalization {\n\t/// Gets the current language by language key e.g. `en_US` or `de_DE`.\n\tfn language(\u0026self) -\u003e \u0026String {\n\t\t...\n\t}\n\n\t/// Sets the current language by key e.g. `en_US` or `de_DE`.\n\tfn set_language(\u0026mut self, key: \u0026str) {\n\t\t...\n\t}\n\n\t/// Gets the translated text for the given key. If there is no given translation the `key` will be returned as result.\n\tfn text(\u0026self, key: String) -\u003e String {\n\t\t...\n\t}\n}\n```\n\nIt is possible to register a localization service for an\napplication. Simply make use of the\n[RonLocalization](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/localization/ron_localization/mod.rs),\nthat can read localization dictionaries coded in the\n[RON](https://github.com/ron-rs/ron) format.\n\n*Example*\n\n```rust\nlet de_de = r#\"\n\tDictionary(\n\t\twords: {\n\t\t\t\"hello\": \"Hallo\",\n\t\t\t\"world\": \"Welt\",\n\t\t}\n\t)\n\t\"#;\n\nApplication::new()\n\t.localization(\n\t\tRonLocalization::create()\n\t\t\t// sets the initial language\n\t\t\t.language(\"en_US\")\n\t\t\t// adds an language dictionary to the localization service.\n\t\t\t.dictionary(\"de_DE\", de_de)\n\t\t\t.build()\n\t)\n\t.window(|ctx| {\n\t\tWindow::new()\n\t\t\t.title(\"OrbTk - showcase example\")\n\t\t\t.position((100, 100))\n\t\t\t.size(600, 730)\n\t\t\t.resizable(true)\n\t\t\t.child(TextBlock::new().text(\"hello\").build(ctx))\n\t\t\t.build(ctx)\n\t})\n\t.run();\n```\n\nInside this example code the `text` property (value **hello**) is used\nas the `key`. This key is matched to the correponding `value` inside the\ndictionary of the corresponding localization service. If you haven't defined a\ndictionary for the current language, OrbTk will simply take the value of the property itself.\nYou are free to start development without and any localization, but add it afterwards.\n\nYou may switch the language at runtime. Inside the state widget you simply consume the `set_language` method, that is accessible via the\n[Context](https://github.com/redox-os/orbtk/blob/develop/orbtk_core/src/widget_base/context.rs)\nstructure.\n\n## Run Examples\n\n### Build with sdl2 installation\n\nIf your target Operating-System is `Linux`, `macOS` or `Windows`, a\n`sdl2` installation is required. Please check the documentation that\nis provieded for th [`rust-sdk2` crate](\nhttps://github.com/Rust-SDL2/rust-sdl2).\n\n### Build with sdl2 from source\n\nAs an alternative, you may build `OrbTk` while bundling `sdl2`. To activate the `bundled` feature go ahead like this:\n\n```shell\ncargo run --example showcase --features bundled\n```\n\nPlease asure, that you `toolchain` will provide a *working* C compiler (e.g. `gcc`, `clang`, or MS's compiler).\n\nTo target `linux`, you also need to provide `cmake`:\n\n```shell\nsudo apt install cmake\n```\n\nIf you have trouble build the provided OrbTk examples or simply don't want to\nuse a C compiler, please check the backend section. It contains\nalternatives.\n\nAll example source-code resides inside the [`examples` subdirectory](./orbtk/examples) of the orbtk subcrate.\n\nCompile, start and play around with the `showcase` example while executing the following command:\n\n```text\ncargo run --example showcase --release\n```\n\nOrbTk has an integrated `debug` tools. It will oultline the bounds of\nall managed widgets inside the widget tree. This will include\ninvisible ones.  You may also want to print out the tree structure of your app.\nThis is activated, via feature flags like this:\n\n```text\ncargo run --example showcase --release --features \"debug, log\"\n```\n\n## Run Examples with cargo-node\n\nTo run the examples as a browser, electron or cordova app you have to install cargo-node:\n\n```text\ncargo install -f cargo-node\n```\n\n`cargo-node` itself relies on `npm` version 6.9.0, which is included with `Node.js` version 10.16.3. You can download it\nfrom  its [homepage](https://nodejs.org/dist/v10.16.3/).\n\nRust's `cargo` is also required. All cargo-node's dependencies are installed automatically.\n\n### Start examples\n\nTo start the `showcase` example as a node binary, executing one of the following commands:\n\n* Run as browser app:\n\n```text\ncargo node run --target browser --example showcase\n```\n\n* Run as electron app:\n\n```text\ncargo node run --target electron --example showcase\n```\n\n* Run as cordova app on android:\n\n```text\ncargo node run --target android --example showcase\n```\n\n## crates structure\n\n* orbtk: sub-crate, that provides all needed components to build an OrbTk `cross platform UI`.\n* orbtk_core: sub-crate, that provides the `core components` of Orbtk (widget basics, tree handling, theming)\n* orbtk_orbclient: sub-crate, that handles cross platform aware `window and event management`. It is based on **OrbClient**.\n* orbtk_tinyskia: Wrapper methods that consumes the **tiny-skia** `2D rendering engine`.\n* orbtk_widgets: sub-crate providing the standard OrbTk `widget library` and and `theming support`.\n\n## Inspirations\n\n* [Flutter](https://flutter.io/)\n* [React](https://reactjs.org/)\n* [Yew](https://github.com/DenisKolodin/yew)\n\n## Showcases\n\n* [Plural Planner](https://codeberg.org/flovanco/Plural): Task app\n* [Space Editor](https://codeberg.org/flovanco/space-editor): 2D Tile Map Editor compatible with OrbGame\n* [twin-commander](https://github.com/kivimango/twin-commander): A twin-panel file manager specifically for the Redox OS\n\n## Contribution\n\nIf you want to help and improve OrbTk submit your feedback via the\n[issue tracker](https://github.com/redox-os/orbtk/issues). All pull\nrequests are welcome and will be reviewed. You can also discuss with\nother OrbTk developers via the [Redox chat\ninterface](https://redox-os.org/community/). Please join the **orbtk**\nchannel.\n\n#### Contribution check list\n\n* Please document for all your `pub` structs, traits and functions.\n* Please add suitable tests methods.\n* Use static \u0026str for widget ids and new style definitions.\n* For widget development check ProgressBar or Slider as an example.\n* Add your changes inside  CHANGELOG.md\n* Extend the example section to show consumption of your code.\n* Always run `cargo fmt` before uploading.\n* Please run `cargo cippy` before uploading.\n* Create the PR using our template.\n\n## License\n\n\u003c!-- License source --\u003e\n[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png \"Creative Common Logo\"\n[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode \"Creative Common License\"\n\nSource-Code is licensed under MIT license ([LICENSE](LICENSE)).\n\n© 2017-2022 Jeremy Soller\u003cbr\u003e\n© 2018-2022 Florian Blasius\n\nThis documentation work is licensed under a [Creative Common License 4.0][License-CC_BY]\n\n![Creative Common Logo][Logo-CC_BY]\n\n© 2020-2022 Ralf Zerres\n","funding_links":[],"categories":["Rust","Libraries","库 Libraries"],"sub_categories":["GUI","GUI GUI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredox-os%2Forbtk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredox-os%2Forbtk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredox-os%2Forbtk/lists"}