76698ff2b5
This allows us to introduce a platform-specific `Action` to both `iced_native` and `iced_web` and remove the `Clipboard` from `Application::update` to maintain purity. Additionally, this should let us implement further actions to let users query and modify the shell environment (e.g. window, clipboard, and more!)
332 lines
11 KiB
Rust
332 lines
11 KiB
Rust
use crate::window;
|
|
use crate::{Color, Command, Element, Executor, Menu, Settings, Subscription};
|
|
|
|
/// An interactive cross-platform application.
|
|
///
|
|
/// This trait is the main entrypoint of Iced. Once implemented, you can run
|
|
/// your GUI application by simply calling [`run`](#method.run).
|
|
///
|
|
/// - On native platforms, it will run in its own window.
|
|
/// - On the web, it will take control of the `<title>` and the `<body>` of the
|
|
/// document.
|
|
///
|
|
/// An [`Application`] can execute asynchronous actions by returning a
|
|
/// [`Command`] in some of its methods. If you do not intend to perform any
|
|
/// background work in your program, the [`Sandbox`] trait offers a simplified
|
|
/// interface.
|
|
///
|
|
/// When using an [`Application`] with the `debug` feature enabled, a debug view
|
|
/// can be toggled by pressing `F12`.
|
|
///
|
|
/// # Examples
|
|
/// [The repository has a bunch of examples] that use the [`Application`] trait:
|
|
///
|
|
/// - [`clock`], an application that uses the [`Canvas`] widget to draw a clock
|
|
/// and its hands to display the current time.
|
|
/// - [`download_progress`], a basic application that asynchronously downloads
|
|
/// a dummy file of 100 MB and tracks the download progress.
|
|
/// - [`events`], a log of native events displayed using a conditional
|
|
/// [`Subscription`].
|
|
/// - [`game_of_life`], an interactive version of the [Game of Life], invented
|
|
/// by [John Horton Conway].
|
|
/// - [`pokedex`], an application that displays a random Pokédex entry (sprite
|
|
/// included!) by using the [PokéAPI].
|
|
/// - [`solar_system`], an animated solar system drawn using the [`Canvas`] widget
|
|
/// and showcasing how to compose different transforms.
|
|
/// - [`stopwatch`], a watch with start/stop and reset buttons showcasing how
|
|
/// to listen to time.
|
|
/// - [`todos`], a todos tracker inspired by [TodoMVC].
|
|
///
|
|
/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.3/examples
|
|
/// [`clock`]: https://github.com/hecrj/iced/tree/0.3/examples/clock
|
|
/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.3/examples/download_progress
|
|
/// [`events`]: https://github.com/hecrj/iced/tree/0.3/examples/events
|
|
/// [`game_of_life`]: https://github.com/hecrj/iced/tree/0.3/examples/game_of_life
|
|
/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.3/examples/pokedex
|
|
/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.3/examples/solar_system
|
|
/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.3/examples/stopwatch
|
|
/// [`todos`]: https://github.com/hecrj/iced/tree/0.3/examples/todos
|
|
/// [`Sandbox`]: crate::Sandbox
|
|
/// [`Canvas`]: crate::widget::Canvas
|
|
/// [PokéAPI]: https://pokeapi.co/
|
|
/// [TodoMVC]: http://todomvc.com/
|
|
///
|
|
/// ## A simple "Hello, world!"
|
|
///
|
|
/// If you just want to get started, here is a simple [`Application`] that
|
|
/// says "Hello, world!":
|
|
///
|
|
/// ```no_run
|
|
/// use iced::{executor, Application, Clipboard, Command, Element, Settings, Text};
|
|
///
|
|
/// pub fn main() -> iced::Result {
|
|
/// Hello::run(Settings::default())
|
|
/// }
|
|
///
|
|
/// struct Hello;
|
|
///
|
|
/// impl Application for Hello {
|
|
/// type Executor = executor::Default;
|
|
/// type Message = ();
|
|
/// type Flags = ();
|
|
///
|
|
/// fn new(_flags: ()) -> (Hello, Command<Self::Message>) {
|
|
/// (Hello, Command::none())
|
|
/// }
|
|
///
|
|
/// fn title(&self) -> String {
|
|
/// String::from("A cool application")
|
|
/// }
|
|
///
|
|
/// fn update(&mut self, _message: Self::Message) -> Command<Self::Message> {
|
|
/// Command::none()
|
|
/// }
|
|
///
|
|
/// fn view(&mut self) -> Element<Self::Message> {
|
|
/// Text::new("Hello, world!").into()
|
|
/// }
|
|
/// }
|
|
/// ```
|
|
pub trait Application: Sized {
|
|
/// The [`Executor`] that will run commands and subscriptions.
|
|
///
|
|
/// The [default executor] can be a good starting point!
|
|
///
|
|
/// [`Executor`]: Self::Executor
|
|
/// [default executor]: crate::executor::Default
|
|
type Executor: Executor;
|
|
|
|
/// The type of __messages__ your [`Application`] will produce.
|
|
type Message: std::fmt::Debug + Clone + Send;
|
|
|
|
/// The data needed to initialize your [`Application`].
|
|
type Flags;
|
|
|
|
/// Initializes the [`Application`] with the flags provided to
|
|
/// [`run`] as part of the [`Settings`].
|
|
///
|
|
/// Here is where you should return the initial state of your app.
|
|
///
|
|
/// Additionally, you can return a [`Command`] if you need to perform some
|
|
/// async action in the background on startup. This is useful if you want to
|
|
/// load state from a file, perform an initial HTTP request, etc.
|
|
///
|
|
/// [`run`]: Self::run
|
|
fn new(flags: Self::Flags) -> (Self, Command<Self::Message>);
|
|
|
|
/// Returns the current title of the [`Application`].
|
|
///
|
|
/// This title can be dynamic! The runtime will automatically update the
|
|
/// title of your application when necessary.
|
|
fn title(&self) -> String;
|
|
|
|
/// Handles a __message__ and updates the state of the [`Application`].
|
|
///
|
|
/// This is where you define your __update logic__. All the __messages__,
|
|
/// produced by either user interactions or commands, will be handled by
|
|
/// this method.
|
|
///
|
|
/// Any [`Command`] returned will be executed immediately in the background.
|
|
fn update(&mut self, message: Self::Message) -> Command<Self::Message>;
|
|
|
|
/// Returns the event [`Subscription`] for the current state of the
|
|
/// application.
|
|
///
|
|
/// A [`Subscription`] will be kept alive as long as you keep returning it,
|
|
/// and the __messages__ produced will be handled by
|
|
/// [`update`](#tymethod.update).
|
|
///
|
|
/// By default, this method returns an empty [`Subscription`].
|
|
fn subscription(&self) -> Subscription<Self::Message> {
|
|
Subscription::none()
|
|
}
|
|
|
|
/// Returns the widgets to display in the [`Application`].
|
|
///
|
|
/// These widgets can produce __messages__ based on user interaction.
|
|
fn view(&mut self) -> Element<'_, Self::Message>;
|
|
|
|
/// Returns the current [`Application`] mode.
|
|
///
|
|
/// The runtime will automatically transition your application if a new mode
|
|
/// is returned.
|
|
///
|
|
/// Currently, the mode only has an effect in native platforms.
|
|
///
|
|
/// By default, an application will run in windowed mode.
|
|
fn mode(&self) -> window::Mode {
|
|
window::Mode::Windowed
|
|
}
|
|
|
|
/// Returns the background color of the [`Application`].
|
|
///
|
|
/// By default, it returns [`Color::WHITE`].
|
|
fn background_color(&self) -> Color {
|
|
Color::WHITE
|
|
}
|
|
|
|
/// Returns the scale factor of the [`Application`].
|
|
///
|
|
/// 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 scale_factor(&self) -> f64 {
|
|
1.0
|
|
}
|
|
|
|
/// Returns whether the [`Application`] should be terminated.
|
|
///
|
|
/// By default, it returns `false`.
|
|
fn should_exit(&self) -> bool {
|
|
false
|
|
}
|
|
|
|
/// Returns the current system [`Menu`] of the [`Application`].
|
|
///
|
|
/// By default, it returns an empty [`Menu`].
|
|
fn menu(&self) -> Menu<Self::Message> {
|
|
Menu::new()
|
|
}
|
|
|
|
/// Runs the [`Application`].
|
|
///
|
|
/// On native platforms, this method will take control of the current thread
|
|
/// and __will NOT return__ unless there is an [`Error`] during startup.
|
|
///
|
|
/// It should probably be that last thing you call in your `main` function.
|
|
///
|
|
/// [`Error`]: crate::Error
|
|
fn run(settings: Settings<Self::Flags>) -> crate::Result
|
|
where
|
|
Self: 'static,
|
|
{
|
|
#[cfg(not(target_arch = "wasm32"))]
|
|
{
|
|
let renderer_settings = crate::renderer::Settings {
|
|
default_font: settings.default_font,
|
|
default_text_size: settings.default_text_size,
|
|
text_multithreading: settings.text_multithreading,
|
|
antialiasing: if settings.antialiasing {
|
|
Some(crate::renderer::settings::Antialiasing::MSAAx4)
|
|
} else {
|
|
None
|
|
},
|
|
..crate::renderer::Settings::from_env()
|
|
};
|
|
|
|
Ok(crate::runtime::application::run::<
|
|
Instance<Self>,
|
|
Self::Executor,
|
|
crate::renderer::window::Compositor,
|
|
>(settings.into(), renderer_settings)?)
|
|
}
|
|
|
|
#[cfg(target_arch = "wasm32")]
|
|
{
|
|
<Instance<Self> as iced_web::Application>::run(settings.flags);
|
|
|
|
Ok(())
|
|
}
|
|
}
|
|
}
|
|
|
|
struct Instance<A: Application>(A);
|
|
|
|
#[cfg(not(target_arch = "wasm32"))]
|
|
impl<A> iced_winit::Program for Instance<A>
|
|
where
|
|
A: Application,
|
|
{
|
|
type Renderer = crate::renderer::Renderer;
|
|
type Message = A::Message;
|
|
|
|
fn update(&mut self, message: Self::Message) -> Command<Self::Message> {
|
|
self.0.update(message)
|
|
}
|
|
|
|
fn view(&mut self) -> Element<'_, Self::Message> {
|
|
self.0.view()
|
|
}
|
|
}
|
|
|
|
#[cfg(not(target_arch = "wasm32"))]
|
|
impl<A> crate::runtime::Application for Instance<A>
|
|
where
|
|
A: Application,
|
|
{
|
|
type Flags = A::Flags;
|
|
|
|
fn new(flags: Self::Flags) -> (Self, Command<A::Message>) {
|
|
let (app, command) = A::new(flags);
|
|
|
|
(Instance(app), command)
|
|
}
|
|
|
|
fn title(&self) -> String {
|
|
self.0.title()
|
|
}
|
|
|
|
fn mode(&self) -> iced_winit::Mode {
|
|
match self.0.mode() {
|
|
window::Mode::Windowed => iced_winit::Mode::Windowed,
|
|
window::Mode::Fullscreen => iced_winit::Mode::Fullscreen,
|
|
window::Mode::Hidden => iced_winit::Mode::Hidden,
|
|
}
|
|
}
|
|
|
|
fn subscription(&self) -> Subscription<Self::Message> {
|
|
self.0.subscription()
|
|
}
|
|
|
|
fn background_color(&self) -> Color {
|
|
self.0.background_color()
|
|
}
|
|
|
|
fn scale_factor(&self) -> f64 {
|
|
self.0.scale_factor()
|
|
}
|
|
|
|
fn should_exit(&self) -> bool {
|
|
self.0.should_exit()
|
|
}
|
|
|
|
fn menu(&self) -> Menu<Self::Message> {
|
|
self.0.menu()
|
|
}
|
|
}
|
|
|
|
#[cfg(target_arch = "wasm32")]
|
|
impl<A> iced_web::Application for Instance<A>
|
|
where
|
|
A: Application,
|
|
{
|
|
type Executor = A::Executor;
|
|
type Message = A::Message;
|
|
type Flags = A::Flags;
|
|
|
|
fn new(flags: Self::Flags) -> (Self, Command<A::Message>) {
|
|
let (app, command) = A::new(flags);
|
|
|
|
(Instance(app), command)
|
|
}
|
|
|
|
fn title(&self) -> String {
|
|
self.0.title()
|
|
}
|
|
|
|
fn update(&mut self, message: Self::Message) -> Command<Self::Message> {
|
|
self.0.update(message)
|
|
}
|
|
|
|
fn subscription(&self) -> Subscription<Self::Message> {
|
|
self.0.subscription()
|
|
}
|
|
|
|
fn view(&mut self) -> Element<'_, Self::Message> {
|
|
self.0.view()
|
|
}
|
|
}
|