diff options
| author |  Héctor Ramón Jiménez <hector0193@gmail.com> | 2019-11-22 19:36:57 +0100 |
|---|---|---|
| committer | Héctor Ramón Jiménez <hector0193@gmail.com> | 2019-11-22 19:36:57 +0100 |
| commit | a7dba612f03e58d7bd9527499d893987986b347c (patch) | |
| tree | b8c3d8f997b714aa368bd6eaecf14065f7645c77 /src/application.rs | |
| parent | ba56a561b254c9a5f3d23cb54d23dc311759ab4c (diff) | |
| download | iced-a7dba612f03e58d7bd9527499d893987986b347c.tar.gz iced-a7dba612f03e58d7bd9527499d893987986b347c.tar.bz2 iced-a7dba612f03e58d7bd9527499d893987986b347c.zip | |
Write docs for `iced` and `iced_native`
Diffstat (limited to 'src/application.rs')
| -rw-r--r-- | src/application.rs | 129 |
1 files changed, 125 insertions, 4 deletions
diff --git a/src/application.rs b/src/application.rs index ba8da446..5ecb901e 100644 --- a/src/application.rs +++ b/src/application.rs @@ -1,19 +1,140 @@ use crate::{Command, Element}; +/// 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`](trait.Application.html) can execute asynchronous actions +/// by returning a [`Command`](struct.Command.html) in some of its methods. If +/// you do not intend to perform any background work in your program, the +/// [`Sandbox`](trait.Sandbox.html) trait offers a simplified interface. +/// +/// # Example +/// Let's say we want to run the [`Counter` example we implemented +/// before](index.html#overview). We just need to fill in the gaps: +/// +/// ```no_run +/// use iced::{button, Application, Button, Column, Command, Element, Text}; +/// +/// pub fn main() { +/// Counter::run() +/// } +/// +/// #[derive(Default)] +/// struct Counter { +/// value: i32, +/// increment_button: button::State, +/// decrement_button: button::State, +/// } +/// +/// #[derive(Debug, Clone, Copy)] +/// enum Message { +/// IncrementPressed, +/// DecrementPressed, +/// } +/// +/// impl Application for Counter { +/// type Message = Message; +/// +/// fn new() -> (Self, Command<Message>) { +/// (Self::default(), Command::none()) +/// } +/// +/// fn title(&self) -> String { +/// String::from("A simple counter") +/// } +/// +/// fn update(&mut self, message: Message) -> Command<Message> { +/// match message { +/// Message::IncrementPressed => { +/// self.value += 1; +/// } +/// Message::DecrementPressed => { +/// self.value -= 1; +/// } +/// } +/// +/// Command::none() +/// } +/// +/// fn view(&mut self) -> Element<Message> { +/// Column::new() +/// .push( +/// Button::new(&mut self.increment_button, Text::new("Increment")) +/// .on_press(Message::IncrementPressed), +/// ) +/// .push( +/// Text::new(self.value.to_string()).size(50), +/// ) +/// .push( +/// Button::new(&mut self.decrement_button, Text::new("Decrement")) +/// .on_press(Message::DecrementPressed), +/// ) +/// .into() +/// } +/// } +/// ``` pub trait Application: Sized { + /// The type of __messages__ your [`Application`] will produce. + /// + /// [`Application`]: trait.Application.html type Message: std::fmt::Debug + Send; + /// Initializes the [`Application`]. + /// + /// Here is where you should return the initial state of your app. + /// + /// Additionally, you can return a [`Command`](struct.Command.html) 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. + /// + /// [`Application`]: trait.Application.html fn new() -> (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. + /// + /// [`Application`]: trait.Application.html 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. + /// + /// [`Application`]: trait.Application.html + /// [`Command`]: struct.Command.html fn update(&mut self, message: Self::Message) -> Command<Self::Message>; - fn view(&mut self) -> Element<Self::Message>; - + /// Returns the widgets to display in the [`Application`]. + /// + /// These widgets can produce __messages__ based on user interaction. + /// + /// [`Application`]: trait.Application.html + fn view(&mut self) -> Element<'_, Self::Message>; + + /// Runs the [`Application`]. + /// + /// 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. + /// + /// [`Application`]: trait.Application.html fn run() where - Self: 'static + Sized, + Self: 'static, { #[cfg(not(target_arch = "wasm32"))] <Instance<Self> as iced_winit::Application>::run(); @@ -47,7 +168,7 @@ where self.0.update(message) } - fn view(&mut self) -> Element<Self::Message> { + fn view(&mut self) -> Element<'_, Self::Message> { self.0.view() } } |