me/iced
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Introduce daemon API and unify shell runtimes

Browse source
This commit is contained in:
Héctor Ramón Jiménez 2024-06-19 01:53:40 +02:00
parent 368b15f708
commit 341c9a3c12
No known key found for this signature in database
GPG key ID: 7CC46565708259A7
54 changed files with 1352 additions and 2677 deletions
Download patch file Download diff file Expand all files Collapse all files

616
src/application.rs
View file

@ -1,278 +1,426 @@
//! Build interactive cross-platform applications.
use crate::core::text;
use crate::graphics::compositor;
use crate::shell::application;
use crate::{Element, Executor, Settings, Subscription, Task};
//! Create and run iced applications step by step.
//!
//! # Example
//! ```no_run
//! use iced::widget::{button, column, text, Column};
//! use iced::Theme;
//!
//! pub fn main() -> iced::Result {
//! iced::application("A counter", update, view)
//! .theme(|_| Theme::Dark)
//! .centered()
//! .run()
//! }
//!
//! #[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),
//! ]
//! }
//! ```
use crate::program::{self, Program};
use crate::window;
use crate::{Element, Font, Result, Settings, Size, Subscription, Task};
pub use application::{Appearance, DefaultStyle};
use std::borrow::Cow;
/// 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
/// [`Task`] in some of its methods.
///
/// 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/iced-rs/iced/tree/0.12/examples
/// [`clock`]: https://github.com/iced-rs/iced/tree/0.12/examples/clock
/// [`download_progress`]: https://github.com/iced-rs/iced/tree/0.12/examples/download_progress
/// [`events`]: https://github.com/iced-rs/iced/tree/0.12/examples/events
/// [`game_of_life`]: https://github.com/iced-rs/iced/tree/0.12/examples/game_of_life
/// [`pokedex`]: https://github.com/iced-rs/iced/tree/0.12/examples/pokedex
/// [`solar_system`]: https://github.com/iced-rs/iced/tree/0.12/examples/solar_system
/// [`stopwatch`]: https://github.com/iced-rs/iced/tree/0.12/examples/stopwatch
/// [`todos`]: https://github.com/iced-rs/iced/tree/0.12/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!":
pub use crate::shell::program::{Appearance, DefaultStyle};
/// Creates an iced [`Application`] given its title, update, and view logic.
///
/// # Example
/// ```no_run
/// use iced::advanced::Application;
/// use iced::executor;
/// use iced::{Task, Element, Settings, Theme, Renderer};
/// use iced::widget::{button, column, text, Column};
///
/// pub fn main() -> iced::Result {
/// Hello::run(Settings::default())
/// iced::application("A counter", update, view).run()
/// }
///
/// struct Hello;
/// #[derive(Debug, Clone)]
/// enum Message {
/// Increment,
/// }
///
/// impl Application for Hello {
/// type Executor = executor::Default;
/// type Flags = ();
/// type Message = ();
/// type Theme = Theme;
/// type Renderer = Renderer;
///
/// fn new(_flags: ()) -> (Hello, Task<Self::Message>) {
/// (Hello, Task::none())
/// fn update(value: &mut u64, message: Message) {
/// match message {
/// Message::Increment => *value += 1,
/// }
/// }
///
/// fn title(&self) -> String {
/// String::from("A cool application")
/// }
///
/// fn update(&mut self, _message: Self::Message) -> Task<Self::Message> {
/// Task::none()
/// }
///
/// fn view(&self) -> Element<Self::Message> {
/// "Hello, world!".into()
/// }
/// fn view(value: &u64) -> Column<Message> {
/// column![
/// text(value),
/// button("+").on_press(Message::Increment),
/// ]
/// }
/// ```
pub trait Application: Sized
pub fn application<State, Message, Theme, Renderer>(
title: impl Title<State>,
update: impl Update<State, Message>,
view: impl for<'a> self::View<'a, State, Message, Theme, Renderer>,
) -> Application<impl Program<State = State, Message = Message, Theme = Theme>>
where
Self::Theme: DefaultStyle,
State: 'static,
Message: Send + std::fmt::Debug + 'static,
Theme: Default + DefaultStyle,
Renderer: program::Renderer,
{
/// 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;
use std::marker::PhantomData;
/// The type of __messages__ your [`Application`] will produce.
type Message: std::fmt::Debug + Send;
/// The theme of your [`Application`].
type Theme: Default;
/// The renderer of your [`Application`].
type Renderer: text::Renderer + compositor::Default;
/// 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 [`Task`] 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, Task<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 [`Task`] returned will be executed immediately in the background.
fn update(&mut self, message: Self::Message) -> Task<Self::Message>;
/// Returns the widgets to display in the [`Application`].
///
/// These widgets can produce __messages__ based on user interaction.
fn view(&self) -> Element<'_, Self::Message, Self::Theme, Self::Renderer>;
/// Returns the current [`Theme`] of the [`Application`].
///
/// [`Theme`]: Self::Theme
fn theme(&self) -> Self::Theme {
Self::Theme::default()
struct Instance<State, Message, Theme, Renderer, Update, View> {
update: Update,
view: View,
_state: PhantomData<State>,
_message: PhantomData<Message>,
_theme: PhantomData<Theme>,
_renderer: PhantomData<Renderer>,
}
/// Returns the current [`Appearance`] of the [`Application`].
fn style(&self, theme: &Self::Theme) -> Appearance {
theme.default_style()
impl<State, Message, Theme, Renderer, Update, View> Program
for Instance<State, Message, Theme, Renderer, Update, View>
where
Message: Send + std::fmt::Debug + 'static,
Theme: Default + DefaultStyle,
Renderer: program::Renderer,
Update: self::Update<State, Message>,
View: for<'a> self::View<'a, State, Message, Theme, Renderer>,
{
type State = State;
type Message = Message;
type Theme = Theme;
type Renderer = Renderer;
type Executor = iced_futures::backend::default::Executor;
fn load(&self) -> Task<Self::Message> {
Task::none()
}
fn update(
&self,
state: &mut Self::State,
message: Self::Message,
) -> Task<Self::Message> {
self.update.update(state, message).into()
}
fn view<'a>(
&self,
state: &'a Self::State,
_window: window::Id,
) -> Element<'a, Self::Message, Self::Theme, Self::Renderer> {
self.view.view(state).into()
}
}
/// 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()
Application {
raw: Instance {
update,
view,
_state: PhantomData,
_message: PhantomData,
_theme: PhantomData,
_renderer: PhantomData,
},
settings: Settings::default(),
window: window::Settings::default(),
}
.title(title)
}
/// 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
}
/// The underlying definition and configuration of an iced application.
///
/// You can use this API to create and run iced applications
/// step by step—without coupling your logic to a trait
/// or a specific type.
///
/// You can create an [`Application`] with the [`application`] helper.
#[derive(Debug)]
pub struct Application<P: Program> {
raw: P,
settings: Settings,
window: window::Settings,
}
impl<P: Program> Application<P> {
/// Runs the [`Application`].
///
/// On native platforms, this method will take control of the current thread
/// until the [`Application`] exits.
/// The state of the [`Application`] must implement [`Default`].
/// If your state does not implement [`Default`], use [`run_with`]
/// instead.
///
/// On the web platform, this method __will NOT return__ unless there is an
/// [`Error`] during startup.
///
/// [`Error`]: crate::Error
fn run(settings: Settings<Self::Flags>) -> crate::Result
/// [`run_with`]: Self::run_with
pub fn run(self) -> Result
where
Self: 'static,
P::State: Default,
{
#[allow(clippy::needless_update)]
let renderer_settings = crate::graphics::Settings {
default_font: settings.default_font,
default_text_size: settings.default_text_size,
antialiasing: if settings.antialiasing {
Some(crate::graphics::Antialiasing::MSAAx4)
} else {
None
self.run_with(P::State::default)
}
/// Runs the [`Application`] with a closure that creates the initial state.
pub fn run_with<I>(self, initialize: I) -> Result
where
Self: 'static,
I: Fn() -> P::State + Clone + 'static,
{
self.raw
.run_with(self.settings, Some(self.window), initialize)
}
/// Sets the [`Settings`] that will be used to run the [`Application`].
pub fn settings(self, settings: Settings) -> Self {
Self { settings, ..self }
}
/// Sets the [`Settings::antialiasing`] of the [`Application`].
pub fn antialiasing(self, antialiasing: bool) -> Self {
Self {
settings: Settings {
antialiasing,
..self.settings
},
..crate::graphics::Settings::default()
};
..self
}
}
Ok(crate::shell::application::run::<
Instance<Self>,
Self::Executor,
<Self::Renderer as compositor::Default>::Compositor,
>(settings.into(), renderer_settings)?)
/// Sets the default [`Font`] of the [`Application`].
pub fn default_font(self, default_font: Font) -> Self {
Self {
settings: Settings {
default_font,
..self.settings
},
..self
}
}
/// Adds a font to the list of fonts that will be loaded at the start of the [`Application`].
pub fn font(mut self, font: impl Into<Cow<'static, [u8]>>) -> Self {
self.settings.fonts.push(font.into());
self
}
/// Sets the [`window::Settings::position`] to [`window::Position::Centered`] in the [`Application`].
pub fn centered(self) -> Self {
Self {
window: window::Settings {
position: window::Position::Centered,
..self.window
},
..self
}
}
/// Sets the [`window::Settings::exit_on_close_request`] of the [`Application`].
pub fn exit_on_close_request(self, exit_on_close_request: bool) -> Self {
Self {
window: window::Settings {
exit_on_close_request,
..self.window
},
..self
}
}
/// Sets the [`window::Settings::size`] of the [`Application`].
pub fn window_size(self, size: impl Into<Size>) -> Self {
Self {
window: window::Settings {
size: size.into(),
..self.window
},
..self
}
}
/// Sets the [`window::Settings::transparent`] of the [`Application`].
pub fn transparent(self, transparent: bool) -> Self {
Self {
window: window::Settings {
transparent,
..self.window
},
..self
}
}
/// Sets the [`Title`] of the [`Application`].
pub(crate) fn title(
self,
title: impl Title<P::State>,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_title(self.raw, move |state, _window| {
title.title(state)
}),
settings: self.settings,
window: self.window,
}
}
/// Runs the [`Task`] produced by the closure at startup.
pub fn load(
self,
f: impl Fn() -> Task<P::Message>,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_load(self.raw, f),
settings: self.settings,
window: self.window,
}
}
/// Sets the subscription logic of the [`Application`].
pub fn subscription(
self,
f: impl Fn(&P::State) -> Subscription<P::Message>,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_subscription(self.raw, f),
settings: self.settings,
window: self.window,
}
}
/// Sets the theme logic of the [`Application`].
pub fn theme(
self,
f: impl Fn(&P::State) -> P::Theme,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_theme(self.raw, move |state, _window| f(state)),
settings: self.settings,
window: self.window,
}
}
/// Sets the style logic of the [`Application`].
pub fn style(
self,
f: impl Fn(&P::State, &P::Theme) -> Appearance,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_style(self.raw, f),
settings: self.settings,
window: self.window,
}
}
/// Sets the scale factor of the [`Application`].
pub fn scale_factor(
self,
f: impl Fn(&P::State) -> f64,
) -> Application<
impl Program<State = P::State, Message = P::Message, Theme = P::Theme>,
> {
Application {
raw: program::with_scale_factor(self.raw, move |state, _window| {
f(state)
}),
settings: self.settings,
window: self.window,
}
}
}
struct Instance<A>(A)
where
A: Application,
A::Theme: DefaultStyle;
/// The title logic of some [`Application`].
///
/// This trait is implemented both for `&static str` and
/// any closure `Fn(&State) -> String`.
///
/// This trait allows the [`application`] builder to take any of them.
pub trait Title<State> {
/// Produces the title of the [`Application`].
fn title(&self, state: &State) -> String;
}
impl<A> crate::runtime::Program for Instance<A>
impl<State> Title<State> for &'static str {
fn title(&self, _state: &State) -> String {
self.to_string()
}
}
impl<T, State> Title<State> for T
where
A: Application,
A::Theme: DefaultStyle,
T: Fn(&State) -> String,
{
type Message = A::Message;
type Theme = A::Theme;
type Renderer = A::Renderer;
fn update(&mut self, message: Self::Message) -> Task<Self::Message> {
self.0.update(message)
}
fn view(&self) -> Element<'_, Self::Message, Self::Theme, Self::Renderer> {
self.0.view()
fn title(&self, state: &State) -> String {
self(state)
}
}
impl<A> application::Application for Instance<A>
/// The update logic of some [`Application`].
///
/// This trait allows the [`application`] builder to take any closure that
/// returns any `Into<Task<Message>>`.
pub trait Update<State, Message> {
/// Processes the message and updates the state of the [`Application`].
fn update(
&self,
state: &mut State,
message: Message,
) -> impl Into<Task<Message>>;
}
impl<T, State, Message, C> Update<State, Message> for T
where
A: Application,
A::Theme: DefaultStyle,
T: Fn(&mut State, Message) -> C,
C: Into<Task<Message>>,
{
type Flags = A::Flags;
fn new(flags: Self::Flags) -> (Self, Task<A::Message>) {
let (app, command) = A::new(flags);
(Instance(app), command)
}
fn title(&self) -> String {
self.0.title()
}
fn theme(&self) -> A::Theme {
self.0.theme()
}
fn style(&self, theme: &A::Theme) -> Appearance {
self.0.style(theme)
}
fn subscription(&self) -> Subscription<Self::Message> {
self.0.subscription()
}
fn scale_factor(&self) -> f64 {
self.0.scale_factor()
fn update(
&self,
state: &mut State,
message: Message,
) -> impl Into<Task<Message>> {
self(state, message)
}
}
/// The view logic of some [`Application`].
///
/// This trait allows the [`application`] builder to take any closure that
/// returns any `Into<Element<'_, Message>>`.
pub trait View<'a, State, Message, Theme, Renderer> {
/// Produces the widget of the [`Application`].
fn view(
&self,
state: &'a State,
) -> impl Into<Element<'a, Message, Theme, Renderer>>;
}
impl<'a, T, State, Message, Theme, Renderer, Widget>
View<'a, State, Message, Theme, Renderer> for T
where
T: Fn(&'a State) -> Widget,
State: 'static,
Widget: Into<Element<'a, Message, Theme, Renderer>>,
{
fn view(
&self,
state: &'a State,
) -> impl Into<Element<'a, Message, Theme, Renderer>> {
self(state)
}
}