From 580891dda76f7e9174913eb75e3bee4261866d71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Fri, 22 Nov 2019 22:14:39 +0100 Subject: [PATCH] Write docs for `iced_winit` --- winit/src/application.rs | 55 +++++++++++++++++++++++++++++++++++++++- winit/src/conversion.rs | 26 +++++++++++++++++-- winit/src/lib.rs | 23 +++++++++++++++++ 3 files changed, 101 insertions(+), 3 deletions(-) diff --git a/winit/src/application.rs b/winit/src/application.rs index bf41d0c8..4a5fd66b 100644 --- a/winit/src/application.rs +++ b/winit/src/application.rs @@ -6,19 +6,72 @@ use crate::{ UserInterface, }; +/// An interactive, native 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). It will run in +/// its own window. +/// +/// An [`Application`](trait.Application.html) can execute asynchronous actions +/// by returning a [`Command`](struct.Command.html) in some of its methods. pub trait Application: Sized { + /// The renderer to use to draw the [`Application`]. + /// + /// [`Application`]: trait.Application.html type Renderer: Windowed; + /// 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); + /// 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; - fn view(&mut self) -> Element; + /// 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, Self::Renderer>; + /// 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, diff --git a/winit/src/conversion.rs b/winit/src/conversion.rs index e73fa008..03d583fb 100644 --- a/winit/src/conversion.rs +++ b/winit/src/conversion.rs @@ -1,6 +1,16 @@ -use crate::input::{keyboard::KeyCode, mouse, ButtonState}; -use crate::MouseCursor; +//! Convert [`winit`] types to [`iced_native`] types, and viceversa. +//! +//! [`winit`]: https://github.com/rust-windowing/winit +//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native +use crate::{ + input::{keyboard::KeyCode, mouse, ButtonState}, + MouseCursor, +}; +/// Convert a `MouseCursor` from [`iced_native`] to a [`winit`] cursor icon. +/// +/// [`winit`]: https://github.com/rust-windowing/winit +/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native pub fn mouse_cursor(mouse_cursor: MouseCursor) -> winit::window::CursorIcon { match mouse_cursor { MouseCursor::OutOfBounds => winit::window::CursorIcon::Default, @@ -13,6 +23,10 @@ pub fn mouse_cursor(mouse_cursor: MouseCursor) -> winit::window::CursorIcon { } } +/// Convert a `MouseButton` from [`winit`] to an [`iced_native`] mouse button. +/// +/// [`winit`]: https://github.com/rust-windowing/winit +/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native pub fn mouse_button(mouse_button: winit::event::MouseButton) -> mouse::Button { match mouse_button { winit::event::MouseButton::Left => mouse::Button::Left, @@ -22,6 +36,10 @@ pub fn mouse_button(mouse_button: winit::event::MouseButton) -> mouse::Button { } } +/// Convert an `ElementState` from [`winit`] to an [`iced_native`] button state. +/// +/// [`winit`]: https://github.com/rust-windowing/winit +/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native pub fn button_state(element_state: winit::event::ElementState) -> ButtonState { match element_state { winit::event::ElementState::Pressed => ButtonState::Pressed, @@ -29,6 +47,10 @@ pub fn button_state(element_state: winit::event::ElementState) -> ButtonState { } } +/// Convert a `VirtualKeyCode` from [`winit`] to an [`iced_native`] key code. +/// +/// [`winit`]: https://github.com/rust-windowing/winit +/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native pub fn key_code(virtual_keycode: winit::event::VirtualKeyCode) -> KeyCode { match virtual_keycode { winit::event::VirtualKeyCode::Key1 => KeyCode::Key1, diff --git a/winit/src/lib.rs b/winit/src/lib.rs index a708b1bd..0a2bf7dd 100644 --- a/winit/src/lib.rs +++ b/winit/src/lib.rs @@ -1,3 +1,26 @@ +//! A windowing shell for Iced, on top of [`winit`]. +//! +//! ![`iced_winit` crate graph](https://github.com/hecrj/iced/blob/cae26cb7bc627f4a5b3bcf1cd023a0c552e8c65e/docs/graphs/winit.png?raw=true) +//! +//! `iced_winit` offers some convenient abstractions on top of [`iced_native`] +//! to quickstart development when using [`winit`]. +//! +//! It exposes a renderer-agnostic [`Application`] trait that can be implemented +//! and then run with a simple call. The use of this trait is optional. +//! +//! Additionally, a [`conversion`] module is available for users that decide to +//! implement a custom event loop. +//! +//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native +//! [`winit`]: https://github.com/rust-windowing/winit +//! [`Application`]: trait.Application.html +//! [`conversion`]: conversion +#![deny(missing_docs)] +#![deny(missing_debug_implementations)] +#![deny(unused_results)] +#![deny(unsafe_code)] +#![deny(rust_2018_idioms)] + #[doc(no_inline)] pub use iced_native::*; pub use winit;