Trait iced::Sandbox

source ·
pub trait Sandbox {
    type Message: Debug + Send;

    // Required methods
    fn new() -> Self;
    fn title(&self) -> String;
    fn update(&mut self, message: Self::Message);
    fn view(&self) -> Element<'_, Self::Message>;

    // Provided methods
    fn theme(&self) -> Theme { ... }
    fn style(&self) -> Application { ... }
    fn scale_factor(&self) -> f64 { ... }
    fn run(settings: Settings<()>) -> Result<(), Error>
       where Self: 'static + Sized { ... }
Expand description

A sandboxed Application.

If you are a just getting started with the library, this trait offers a simpler interface than Application.

Unlike an Application, a Sandbox cannot run any asynchronous actions or be initialized with some external flags. However, both traits are very similar and upgrading from a Sandbox is very straightforward.

Therefore, it is recommended to always start by implementing this trait and upgrade only once necessary.


The repository has a bunch of examples that use the Sandbox trait:

  • bezier_tool, a Paint-like tool for drawing Bézier curves using the Canvas widget.
  • counter, the classic counter example explained in the overview.
  • custom_widget, a demonstration of how to build a custom widget that draws a circle.
  • geometry, a custom widget showcasing how to draw geometry with the Mesh2D primitive in iced_wgpu.
  • pane_grid, a grid of panes that can be split, resized, and reorganized.
  • progress_bar, a simple progress bar that can be filled by using a slider.
  • styling, an example showcasing custom styling with a light and dark theme.
  • svg, an application that renders the Ghostscript Tiger by leveraging the Svg widget.
  • tour, a simple UI tour that can run both on native platforms and the web!

§A simple “Hello, world!”

If you just want to get started, here is a simple Sandbox that says “Hello, world!”:

use iced::{Element, Sandbox, Settings};

pub fn main() -> iced::Result {

struct Hello;

impl Sandbox for Hello {
    type Message = ();

    fn new() -> Hello {

    fn title(&self) -> String {
        String::from("A cool application")

    fn update(&mut self, _message: Self::Message) {
        // This application has no interactions

    fn view(&self) -> Element<Self::Message> {
        "Hello, world!".into()

Required Associated Types§


type Message: Debug + Send

The type of messages your Sandbox will produce.

Required Methods§


fn new() -> Self

Initializes the Sandbox.

Here is where you should return the initial state of your app.


fn title(&self) -> String

Returns the current title of the Sandbox.

This title can be dynamic! The runtime will automatically update the title of your application when necessary.


fn update(&mut self, message: Self::Message)

Handles a message and updates the state of the Sandbox.

This is where you define your update logic. All the messages, produced by user interactions, will be handled by this method.


fn view(&self) -> Element<'_, Self::Message>

Returns the widgets to display in the Sandbox.

These widgets can produce messages based on user interaction.

Provided Methods§


fn theme(&self) -> Theme

Returns the current Theme of the Sandbox.

If you want to use your own custom theme type, you will have to use an Application.

By default, it returns Theme::default.


fn style(&self) -> Application

Returns the current style variant of theme::Application.

By default, it returns theme::Application::default.


fn scale_factor(&self) -> f64

Returns the scale factor of the Sandbox.

It can be used to dynamically control the size of the UI at runtime (i.e. zooming).

For instance, a scale factor of 2.0 will make widgets twice as big, while a scale factor of 0.5 will shrink them to half their size.

By default, it returns 1.0.


fn run(settings: Settings<()>) -> Result<(), Error>
where Self: 'static + Sized,

Runs the Sandbox.

On native platforms, this method will take control of the current thread and will NOT return.

It should probably be that last thing you call in your main function.

Object Safety§

This trait is not object safe.