Expand description
Slint
This crate is the main entry point for embedding user interfaces designed with Slint UI in Rust programs.
If you are new to Slint, start with the Walk-through tutorial. If you are already familiar with Slint, the following topics provide related information.
Related topics
- Examples and Recipes
- The
.slintlanguage reference - Builtin Elements
- Builtin Enums
- Widgets
- Positioning and Layout of Elements
- Debugging Techniques
- Slint on Microcontrollers
How to use this crate:
Designs of user interfaces are described in the .slint design markup language. There are three ways
of including them in Rust:
- The
.slintcode is inline in a macro. - The
.slintcode in external files compiled withbuild.rs - The
.slintcode is loaded dynamically at run-time from the file system, by using the interpreter API.
With the first two methods, the markup code is translated to Rust code and each component is turned into a Rust struct with functions. Use these functions to instantiate and show the component, and to access declared properties. Check out our sample component for more information about the generation functions and how to use them.
The .slint code in a macro
This method combines your Rust code with the .slint design markup in one file, using a macro:
slint::slint!{
HelloWorld := Window {
Text {
text: "hello world";
color: green;
}
}
}
fn main() {
HelloWorld::new().run();
}The .slint code in external files is compiled with build.rs
When your design becomes bigger in terms of markup code, you may want move it to a dedicated
.slint file. It’s also possible to split a .slint file into multiple files using modules.
Use a build script to compile
your main .slint file:
In your Cargo.toml add a build assignment and use the slint-build crate in build-dependencies:
[package]
...
build = "build.rs"
edition = "2021"
[dependencies]
slint = "0.3.2"
...
[build-dependencies]
slint-build = "0.3.2"Use the API of the slint-build crate in the build.rs file:
fn main() {
slint_build::compile("ui/hello.slint").unwrap();
}Finally, use the include_modules! macro in your main.rs:
slint::include_modules!();
fn main() {
HelloWorld::new().run();
}The cargo-generate tool is a great tool to up and running quickly with a new Rust project. You can use it in combination with our Template Repository to create a skeleton file hierarchy that uses this method:
cargo install cargo-generate
cargo generate --git https://github.com/slint-ui/slint-rust-templateGenerated components
Currently, only the last component in a .slint source file is mapped to a Rust structure that be instantiated. We are tracking the
resolution of this limitation in https://github.com/slint-ui/slint/issues/784.
The component is generated and re-exported to the location of the include_modules! or slint! macro. It is represented
as a struct with the same name as the component.
For example, if you have
export MyComponent := Window { /*...*/ }in the .slint file, it will create a
struct MyComponent{ /*...*/ }See also our sample component for more information about the API of the generated struct.
A component is instantiated using the fn new() -> Self function. The following
convenience functions are available through the ComponentHandle implementation:
fn clone_strong(&self) -> Self: creates a strongly referenced clone of the component instance.fn as_weak(&self) -> Weak: to create a weak reference to the component instance.fn show(&self): to show the window of the component.fn hide(&self): to hide the window of the component.fn run(&self): a convenience function that first callsshow(), followed by spinning the event loop, andhide()when returning from the event loop.fn global<T: Global<Self>>(&self) -> T: an accessor to the global singletons,
For each top-level property
- A setter
fn set_<property_name>(&self, value: <PropertyType>) - A getter
fn get_<property_name>(&self) -> <PropertyType>
For each top-level callback
fn invoke_<callback_name>(&self): to invoke the callbackfn on_<callback_name>(&self, callback: impl Fn(<CallbackArgs>) + 'static): to set the callback handler.
Note: All dashes (-) are replaced by underscores (_) in names of types or functions.
After instantiating the component, call ComponentHandle::run() on show it on the screen and spin the event loop to
react to input events. To show multiple components simultaneously, call ComponentHandle::show() on each instance.
Call run_event_loop() when you’re ready to enter the event loop.
The generated component struct acts as a handle holding a strong reference (similar to an Rc). The Clone trait is
not implemented. Instead you need to make explicit ComponentHandle::clone_strong and ComponentHandle::as_weak
calls. A strong reference should not be captured by the closures given to a callback, as this would produce a reference
loop and leak the component. Instead, the callback function should capture a weak component.
Threading and Event-loop
For platform-specific reasons, the event loop must run in the main thread, in most backends, and all the components must be created in the same thread as the thread the event loop is running or is going to run.
You should perform the minimum amount of work in the main thread and delegate the actual logic to another
thread to avoid blocking animations. Use the invoke_from_event_loop function to communicate from your worker thread to the UI thread.
To run a function with a delay or with an interval use a Timer.
Type Mappings
The types used for properties in .slint design markup each translate to specific types in Rust.
The follow table summarizes the entire mapping:
.slint Type | Rust Type | Note |
|---|---|---|
int | i32 | |
float | f32 | |
bool | bool | |
string | SharedString | A reference-counted string type that can be easily converted to a str reference. |
color | Color | |
brush | Brush | |
image | Image | |
physical_length | f32 | The unit are physical pixels. |
length | f32 | At run-time, logical lengths are automatically translated to physical pixels using the device pixel ratio. |
duration | i64 | At run-time, durations are always represented as signed 64-bit integers with millisecond precision. |
angle | f32 | The value in degrees |
relative-font-size | f32 | Relative font size factor that is multiplied with the Window.default-font-size and can be converted to a length. |
| structure | struct of the same name | |
| array | ModelRc |
For user defined structures in the .slint, an extra struct is generated.
For example, if the .slint contains
export struct MyStruct := {
foo: int,
bar: string,
}The following struct would be generated:
#[derive(Default, Clone, Debug, PartialEq)]
struct MyStruct {
foo : i32,
bar: slint::SharedString,
}Exported Global singletons
When you export a global singleton from the main file, it is also generated with the exported name. Like the main component, the generated struct have inherent method to access the properties and callback:
For each property
- A setter:
fn set_<property_name>(&self, value: <PropertyType>) - A getter:
fn get_<property_name>(&self) -> <PropertyType>
For each callback
fn invoke_<callback_name>(&self, <CallbackArgs>) -> <ReturnValue>to invoke the callbackfn on_<callback_name>(&self, callback: impl Fn(<CallbackArgs>) + 'static)to set the callback handler.
The global can be accessed with the ComponentHandle::global() function, or with Global::get()
See the documentation of the Global trait for an example.
Feature flags
-
compat-0-3-0(enabled by default) — Mandatory feature: This feature is required to keep the compatibility with Slint 0.3.0 Newer patch version may put current functionality behind a new feature that would be enabled by default only if this feature was added. More info in this blog post -
std(enabled by default) — Enable use of the Rust standard library. -
libm— This feature enables floating point arithmetic emulation using the libm crate. Use this in MCU environments where the processor does not support floating point arithmetic. -
log— If enabled, calls ofdebug()in.slintfiles use to thelog::debug!()macro of the log crate instead of justprintln!(). -
unsafe-single-threaded— Slint uses internally somethread_localstate.When the
stdfeature is enabled, Slint can usestd::thread_local!, but when in a#![no_std]environment, we need a replacement. Using this feature, Slint will just use static variable disregarding Rust’s Send and Sync safetySafety : You must ensure that there is only one single thread that call into the Slint API
Backends
Slint needs a backend that will act as liaison between Slint and the OS.
By default, Slint will use the Qt backend, if Qt is installed, otherwise, it
will use Winit with Femtovg.
Both backends are compiled in. If you want to not compile one of these you need
to disable the default feature and re-enable one backend. It is also possible
to use Slint without backend if you provide the platform abstraction yourself
with platform::set_platform().
If you enable the Winit backend, you need to also include a renderer.
renderer-winit-femtovg is the only stable renderer, the other ones are experimental
It is also possible to select the backend and renderer at runtime when several
are enabled, using the SLINT_BACKEND environment variable.
-
SLINT_BACKEND=Qtselects the Qt backend -
SLINT_BACKEND=winitselects the winit backend -
SLINT_BACKEND=winit-femtovgselects the winit backend with the femtovg renderer -
SLINT_BACKEND=winit-skiaselects the winit backend with the skia renderer -
SLINT_BACKEND=winit-softwareselects the winit backend with the software renderer If the selected backend is not available, the default will be used. -
backend-qt(enabled by default) — The Qt backend feature uses Qt for the windowing system integration and rendering. This backend also provides thenativestyle. It requires Qt 5.15 or later to be installed. If Qt is not installed, the backend will not be operational -
backend-winit(enabled by default) — The winit crate is used for the event loop and windowing system integration. It supports Windows, macOS, web browsers, X11 and Wayland. X11 and wayland are only available when compiling for Linux or other Unix-like operating systems. With this feature, both X11 and Wayland are supported. For a smaller build, omit this feature and select one of the other specificbackend-winit-XXfeatures. -
backend-winit-x11— Simliar tobackend-winitthis enables the winit based event loop but only with support for the X Window System on Unix. -
backend-winit-wayland— Simliar tobackend-winitthis enables the winit based event loop but only with support for the Wayland window system on Unix. -
renderer-winit-femtovg(enabled by default) — Enable thewinitbackend and make it capable of renderer using the femtovg crate. -
renderer-winit-skia— Enable thewinitbackend and make it capable of renderer using Skia -
renderer-winit-skia-opengl— Same asrenderer-winit-skia, but Skia will always use OpenGL. -
renderer-winit-software— Enable thewinitbackend and make it capable of renderer using the software renderer
Modules
Macros
std::format!, but it returns a SharedString instead.slint_build::compile
in your build.rs build script, the use of this macro includes the generated Rust code and makes the exported types
available for you to instantiate..slint design markup language inline in Rust code. Within the braces of the macro
you can use place .slint code and the named exported components will be available for instantiation.Structs
to_ and from_ (a)rgb helper functions:Model.Self::load_from_path.Color.[T].Vec<T>Enums
invoke_from_event_loop() and quit_event_loop() functionset_rendering_notifier on the slint::Window.crate::Window.Window::set_position.Window::set_size.Traits
.slint
markup. Alternatively, you can use ComponentHandle::global to obtain access..slint languageModel::model_tracker and implementation usually
return a reference to its field of ModelNotify.Functions
slint::run_event_loop() will return.Type Definitions
slint::platform::PointerEventButton.slint::platform::WindowEvent.