2020-04-12 07:58:01 +00:00
< h1 align = "center" > LittlevGL - Open-source Embedded GUI Library in Rust< / h1 >
2020-05-30 07:37:40 +00:00
![Original LittlevGL demo image ](lv_demo.png )
2020-04-12 07:58:01 +00:00
< p align = "center" >
LittlevGL provides everything you need to create a Graphical User Interface (GUI) on embedded systems with easy-to-use graphical elements, beautiful visual effects and low memory footprint.
2020-04-12 08:03:02 +00:00
< / p >
< p align = "center" >
2020-04-12 08:10:04 +00:00
LittlevGL is compatible with < samp > #![no_std]< / samp > environments by default.
2020-04-12 07:58:01 +00:00
< / p >
< h4 align = "center" >
2020-05-30 07:37:40 +00:00
< a href = "https://lvgl.io/" > Official LittlevGL Website < / a > ·
2020-04-12 10:32:18 +00:00
< a href = "https://github.com/littlevgl/lvgl" > C library repository< / a > ·
2020-05-30 07:37:40 +00:00
< a href = "https://lvgl.io/demos" > Live demo< / a >
2020-04-12 07:58:01 +00:00
< / h4 >
---
2020-04-12 10:34:03 +00:00
![Rust bindings usage demo code. ](demo.png )
2020-04-12 18:37:26 +00:00
## Usage
Edit your `Cargo.toml` file dependencies with:
```
$ cargo add lvgl
```
The build requires the environment variable bellow to be set:
- `DEP_LV_CONFIG_PATH` : Path to the directory containing the `lv_conf.h` header file used for configuration of LittlevGL library.
We recommend the `lv_conf.h` file to be in your project's root directory. If so, the command to build your project would be:
```shell script
$ DEP_LV_CONFIG_PATH=`pwd` cargo build
```
2020-05-30 18:24:35 +00:00
### Building for embedded environments
We make use of `bindgen` for generating the bindings to LittlevGL at build time. There is a problem in cargo when building
for `no_std` , so we need to use a workaround to build "lvgl-rs". The mainstrem issue in cargo is being tracked at
[rust-lang/cargo#7915 ](https://github.com/rust-lang/cargo/issues/7915 ).
```shell
$ DEP_LV_CONFIG_PATH=`pwd` cargo build -Zfeatures=build_dep
```
#### Requirements / Limitations
LittlevGL C libary do allocate memory dynamically and we need to allocate memory on the heap in the Rust side as well
([`Box`](https://doc.rust-lang.org/beta/alloc/boxed/struct.Box.html)).
That is required, so we can safely provide Rust pointers through FFI. For that reason, we do require
[`alloc` ](https://doc.rust-lang.org/alloc/ ) module to be available.
2020-05-15 10:54:31 +00:00
## Running the demo
2020-05-31 07:12:37 +00:00
[This project contains examples that can run in a desktop simulator. ](./examples )
2020-05-31 16:53:09 +00:00
First, make sure to pull `lvgl-rs` submodules:
2020-05-31 16:51:12 +00:00
```shell
$ git submodule init
$ git submodule update
```
Then run the `demo` example:
2020-05-31 07:12:37 +00:00
```shell
$ DEP_LV_CONFIG_PATH=`pwd`/examples/include cargo run --example demo
```
2020-06-02 07:39:02 +00:00
## Feature Support
The bindings are still in development. There are many features of LVGL that needs to be exposed by `lvgl-rs` . In
this section you can check what is implemented at the moment.
### Features
List of LVGL features that impacts the library usage in general.
- [x] Displays: We use [`embedded_graphics` ](https://docs.rs/embedded-graphics/0.6.2/embedded_graphics/ ) library to
draw to the display. You can use `lvgl-rs` with any of the
[`embedded_graphics` supported displays ](https://docs.rs/embedded-graphics/0.6.2/embedded_graphics/#supported-displays ).
- [x] Events: You can listen and trigger events in widget objects.
2020-06-02 17:21:44 +00:00
- [x] Styles: You can set styles in any exposed object. We are still missing the possibility of defining base styles.
2020-06-02 07:39:02 +00:00
- [ ] Input Devices
- [ ] Fonts
- [ ] Images
- [ ] File system
- [ ] Animations
- [ ] Tasks
### Widgets
- [x] Base object (lv_obj)
- [ ] Arc (lv_arc)
- [x] Bar (lv_bar)
- [x] Button (lv_btn)
2020-06-04 00:00:31 +00:00
- [ ] Button matrix (lv_btnmatrix)
2020-06-02 07:39:02 +00:00
- [ ] Calendar (lv_calendar)
- [ ] Canvas (lv_canvas)
- [ ] Checkbox (lv_cb)
- [ ] Chart (lv_chart)
- [ ] Container (lv_cont)
- [ ] Color picker (lv_cpicker)
2020-06-04 00:00:31 +00:00
- [ ] Drop-down list (lv_dropdown)
2020-06-05 21:22:21 +00:00
- [x] Gauge (lv_gauge)
2020-06-02 07:39:02 +00:00
- [ ] Image (lv_img)
- [ ] Image button (lv_imgbtn)
2020-06-04 00:00:31 +00:00
- [ ] Keyboard (lv_keyboard)
2020-06-02 07:39:02 +00:00
- [x] Label (lv_label)
- [ ] LED (lv_led)
- [ ] Line (lv_line)
- [ ] List (lv_list)
- [ ] Line meter (lv_lmeter)
2020-06-04 00:00:31 +00:00
- [ ] Message box (lv_msdbox)
- [ ] Object mask (lv_objmask)
2020-06-02 07:39:02 +00:00
- [ ] Page (lv_page)
- [ ] Roller (lv_roller)
- [ ] Slider (lv_slider)
- [ ] Spinbox (lv_spinbox)
2020-06-04 00:00:31 +00:00
- [ ] Spinner (lv_spinner)
- [ ] Switch (lv_switch)
2020-06-02 07:39:02 +00:00
- [ ] Table (lv_table)
- [ ] Tabview (lv_tabview)
2020-06-04 00:00:31 +00:00
- [ ] Text area (lv_textarea)
2020-06-02 07:39:02 +00:00
- [ ] Tile view (lv_tileview)
2020-06-05 21:22:21 +00:00
- [ ] Window (lv_win)
2020-06-02 07:39:02 +00:00
Widgets currently implemented might have some missing features. If the widget you want to use is not exposed or
is missing a feature you want to make use, please send a Pull Request or open an issue.