Program API

[hecrj]

This PR introduces a new Program API as a more convenient—although less powerful—alternative to the Sandbox and Application traits.

The main motivation is lowering the learning curve and entry barrier of the library. Specifically, Application has a lot of moving parts (e.g. Flags, Executor, Theme, subscription, etc.)

The run Function

There is a new run function in the root module that can be used to easily run basic applications, like the classic counter:

use iced::widget::{button, column, text, Column};

pub fn main() -> iced::Result {
    iced::run("A counter", update, view)
}

#[derive(Debug, Clone)]
enum Message {
    Increment,
}

fn update(value: &mut u64, message: Message) {
    match message {
        Message::Increment => *value += 1,
    }
}

fn view(value: &u64) -> Column<Message> {
    column![
        text(value),
        button("+").on_press(Message::Increment),
    ]
}

The Program API

The Program API can be used to create and run iced applications step by step—without coupling your logic to a trait or a specific type.

For instance, here is the new main function of the clock example:

pub fn main() -> iced::Result {
    iced::sandbox("Clock - Iced", Clock::update, Clock::view)
        .subscription(Clock::subscription)
        .theme(Clock::theme)
        .antialiased()
        .run()
}

[simdimdim]

? Where can I find the migration guide?
I had a nicely structured App where impl Applicaiton for App was at the root, how should one translate their code to the new model?

[TonalidadeHidrica]

For those who needs a quick migration guide for this API update, I'll briefly introduce how to turn your code to fit into 0.13. It's quite straightforward (than I thought).

If I'm missing something or saying something wrong, please let me know. I hope that it will help other people who are interested in migration!

1. Application and Sandbox traits are gone. Turn your impl Application for App (or impl Sandbox) into a simple impl App. Remove the associated types and leave the other methods as it is. Get rid of your any reference to the associated type (Self::Message) by directly referring to it (Message in this case).
   • Oh by the way, Command was superseded by Task. Just "replace-all" it with your favorite text editor.

-impl Application for App {
-    type Executor = iced::executor::Default;
-    type Flags = ();
-    type Message = Message;
-    type Theme = Theme;
-
-    fn new(_flags: Self::Flags) -> (Self, Command<Message>) {
+impl App {
+    fn new(_flags: ()) -> (Self, Task<Message>) {

2. You can no longer call App::run. Instead, use iced::application function. Provide your title, update, and view function as a function pointer. Then, instantinate your App struct using run_with.

 fn main() -> iced::Result {
-    App::run(Settings::default())
+    iced::application(App::title, App::update, App::view)
+        .run_with(|| App::new(()))
 }

3. Oh hey, have you got subscription, theme, style, or scale_factor in your impl? Just squeeze them in the method chain and you're all set!

 fn main() -> iced::Result {
     iced::application(App::title, App::update, App::view)
+        .subscription(App::subscription)
+        .theme(App::Theme)
         .run_with(|| App::new(()))
 }

4. Whoa, you used to customize Settings to make your app cute? You can place those stuff into the super-convenient method chain too!

 fn main() -> iced::Result {
-    App::run(Settings {
-        default_font: FONT,
-        ..Default::default()
-    })
+    iced::application(App::title, App::update, App::view)
+        .subscription(App::subscription)
+        .theme(App::theme)
+        .default_font(FONT)  // < it's me!
+        .run_with(|| App::new(()))
 }

Note that window options are also flattened into a nice method call.

 fn main() -> iced::Result {
-    App::run(Settings {
-        window: window::Settings {
-            exit_on_close_request: false,
-            ..window::Settings::default()
-        },
-        ..Default::default()
-    })
+    iced::application(App::title, App::update, App::view)
+        .subscription(App::subscription)
+        .exit_on_close_request(false)
+        .run_with(|| App::new(()))
 }

It should be quite obvious from the doc for the Application struct which method corresponds to the stuff you used to use.

Optional refactoring

1. If you don't need to pass arguments to your new implementation, and to create the boostrap Task, you may make your App implement Default so that you can use run instead of run_with.

 fn main() -> iced::Result {
     iced::application(App::title, App::update, App::view)
-        .run_with(|| App::new(()))
+        .run()
 }

-impl App {
-    fn new(_flags: ()) -> (Self, Task<Message>) {
+impl Default for App {
+    fn default() -> Self {

2. You no longer need a function that just returns a static title; you can pass a string literal to the application function.

 fn main() -> iced::Result {
-    iced::application(App::title, App::update, App::view)
+    iced::application("Awesome app", App::update, App::view)
         .run()
 }

 impl App {
-    fn title(&self) -> String {
-        "Awesome app".into()
-    }

3. If your app is simple enough to have only update and view function, there's a shorthand function iced::run.

 fn main() -> iced::Result {
-    iced::application("Awesome app", App::update, App::view)
-        .run()
+    iced::run("Awesome app", App::update, App::view)
 }