logo
pub trait Sandbox {
    type Message: Debug + Send;

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

    fn theme(&self) -> Theme { ... }
    fn style(&self) -> Application { ... }
    fn scale_factor(&self) -> f64 { ... }
    fn should_exit(&self) -> bool { ... }
    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.

Examples

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 {
    Hello::run(Settings::default())
}

struct Hello;

impl Sandbox for Hello {
    type Message = ();

    fn new() -> Hello {
        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

The type of messages your Sandbox will produce.

Required Methods

Initializes the Sandbox.

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

Returns the current title of the Sandbox.

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

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.

Returns the widgets to display in the Sandbox.

These widgets can produce messages based on user interaction.

Provided Methods

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.

Returns the current style variant of theme::Application.

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

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.

Returns whether the Sandbox should be terminated.

By default, it returns false.

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.

Implementors