diff options
Diffstat (limited to '')
34 files changed, 281 insertions, 245 deletions
diff --git a/ECOSYSTEM.md b/ECOSYSTEM.md index 177b8709..65815b96 100644 --- a/ECOSYSTEM.md +++ b/ECOSYSTEM.md @@ -24,7 +24,6 @@ Iced consists of different crates which offer different layers of abstractions f  ### [`iced_core`] - [`iced_core`] holds basic reusable types of the public API. For instance, basic data types like `Point`, `Rectangle`, `Length`, etc. This crate is meant to be a starting point for an Iced runtime. @@ -38,7 +37,7 @@ This crate is meant to be a starting point for an Iced runtime. To achieve this, it introduces a bunch of reusable interfaces: - A `Widget` trait, which is used to implement new widgets: from layout requirements to event and drawing logic. - A bunch of `Renderer` traits, meant to keep the crate renderer-agnostic. -- A `Windowed` trait, leveraging [`raw-window-handle`], which can be implemented by graphical renderers that target _windows_. Window-based shells (like [`iced_winit`]) can use this trait to stay renderer-agnostic. +- A `Backend` trait, leveraging [`raw-window-handle`], which can be implemented by graphical renderers that target _windows_. Window-based shells (like [`iced_winit`]) can use this trait to stay renderer-agnostic. [`druid`]: https://github.com/xi-editor/druid [`raw-window-handle`]: https://github.com/rust-windowing/raw-window-handle @@ -58,8 +57,9 @@ The crate is currently a simple abstraction layer over [`dodrio`]. Currently, [`iced_wgpu`] supports the following primitives: - Text, which is rendered using [`wgpu_glyph`]. No shaping at all. - Quads or rectangles, with rounded borders and a solid background color. -- Images, lazily loaded from the filesystem. - Clip areas, useful to implement scrollables or hide overflowing content. +- Images and SVG, loaded from memory or the file system. +- Meshes of triangles, useful to draw geometry freely. [`wgpu`]: https://github.com/gfx-rs/wgpu-rs [WebGPU API]: https://gpuweb.github.io/gpuweb/ diff --git a/core/CHANGELOG.md b/core/CHANGELOG.md deleted file mode 100644 index c0796e66..00000000 --- a/core/CHANGELOG.md +++ /dev/null @@ -1,19 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] -### Added -- `Color::from_rgb8` to easily build a `Color` from its hexadecimal representation. [#90] - -[#90]: https://github.com/hecrj/iced/pull/90 - - -## [0.1.0] - 2019-11-25 -### Added -- First release! :tada: - -[Unreleased]: https://github.com/hecrj/iced/compare/core-0.1.0...HEAD -[0.1.0]: https://github.com/hecrj/iced/releases/tag/core-0.1.0 diff --git a/core/src/point.rs b/core/src/point.rs index 43ee2143..2b5ad154 100644 --- a/core/src/point.rs +++ b/core/src/point.rs @@ -11,7 +11,7 @@ pub struct Point { } impl Point { - /// The origin (i.e. a [`Point`] with both X=0 and Y=0). + /// The origin (i.e. a [`Point`] at (0, 0)). /// /// [`Point`]: struct.Point.html pub const ORIGIN: Point = Point::new(0.0, 0.0); diff --git a/core/src/size.rs b/core/src/size.rs index 389b3247..4276f05f 100644 --- a/core/src/size.rs +++ b/core/src/size.rs @@ -20,7 +20,7 @@ impl Size { /// [`Size`]: struct.Size.html pub const INFINITY: Size = Size::new(f32::INFINITY, f32::INFINITY); - /// A [`Size`] of infinite width and height. + /// Creates a new [`Size`] with the given width and height. /// /// [`Size`]: struct.Size.html pub const fn new(width: f32, height: f32) -> Self { diff --git a/futures/src/command.rs b/futures/src/command.rs index 535ae4f7..d4f99b82 100644 --- a/futures/src/command.rs +++ b/futures/src/command.rs @@ -7,6 +7,7 @@ use futures::future::{Future, FutureExt}; /// using the `From` trait or [`Command::perform`]. /// /// [`Command`]: struct.Command.html +/// [`Command::perform`]: #method.perform pub struct Command<T> { futures: Vec<BoxFuture<T>>, } diff --git a/futures/src/executor.rs b/futures/src/executor.rs index 5378c0b3..cbd34ee8 100644 --- a/futures/src/executor.rs +++ b/futures/src/executor.rs @@ -56,6 +56,8 @@ pub trait Executor: Sized { /// before creating futures. This method can be leveraged to set up this /// global state, call a function, restore the state, and obtain the result /// of the call. + /// + /// [`Executor`]: trait.Executor.html fn enter<R>(&self, f: impl FnOnce() -> R) -> R { f() } diff --git a/futures/src/subscription.rs b/futures/src/subscription.rs index ab333a20..7a75fc31 100644 --- a/futures/src/subscription.rs +++ b/futures/src/subscription.rs @@ -142,6 +142,18 @@ impl<I, O, H> std::fmt::Debug for Subscription<I, O, H> { /// /// [`Subscription`]: struct.Subscription.html /// [`Recipe`]: trait.Recipe.html +/// +/// # Examples +/// The repository has a couple of [examples] that use a custom [`Recipe`]: +/// +/// - [`download_progress`], a basic application that asynchronously downloads +/// a dummy file of 100 MB and tracks the download progress. +/// - [`stopwatch`], a watch with start/stop and reset buttons showcasing how +/// to listen to time. +/// +/// [examples]: https://github.com/hecrj/iced/tree/0.1/examples +/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.1/examples/download_progress +/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.1/examples/stopwatch pub trait Recipe<Hasher: std::hash::Hasher, Event> { /// The events that will be produced by a [`Subscription`] with this /// [`Recipe`]. diff --git a/futures/src/subscription/tracker.rs b/futures/src/subscription/tracker.rs index efb464b5..c2a0d0f1 100644 --- a/futures/src/subscription/tracker.rs +++ b/futures/src/subscription/tracker.rs @@ -131,6 +131,8 @@ where /// /// This method publishes the given event to all the subscription streams /// currently open. + /// + /// [`Recipe::stream`]: trait.Recipe.html#tymethod.stream pub fn broadcast(&mut self, event: Event) { self.subscriptions .values_mut() diff --git a/native/CHANGELOG.md b/native/CHANGELOG.md deleted file mode 100644 index df8852b7..00000000 --- a/native/CHANGELOG.md +++ /dev/null @@ -1,38 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] -### Added -- `image::Handle` type with `from_path` and `from_memory` methods. [#90] -- `image::Data` enum representing different kinds of image data. [#90] -- `text_input::Renderer::measure_value` required method to measure the width of a `TextInput` value. [#108] -- Click-based cursor positioning for `TextInput`. [#108] -- `Home` and `End` keys support for `TextInput`. [#108] -- `Ctrl+Left` and `Ctrl+Right` cursor word jump for `TextInput`. [#108] -- `keyboard::ModifiersState` struct which contains the state of the keyboard modifiers. [#108] -- `TextInput::password` method to enable secure password input mode. [#113] -- `Button::height` and `Button::min_height` methods to control the height of a button. - -### Changed -- `Image::new` takes an `Into<image::Handle>` now instead of an `Into<String>`. [#90] -- `Button::background` takes an `Into<Background>` now instead of a `Background`. -- `keyboard::Event::Input` now contains key modifiers state. [#108] - -### Fixed -- `Image` widget not keeping aspect ratio consistently. [#90] -- `TextInput` not taking grapheme clusters into account. [#108] - -[#90]: https://github.com/hecrj/iced/pull/90 -[#108]: https://github.com/hecrj/iced/pull/108 -[#113]: https://github.com/hecrj/iced/pull/113 - - -## [0.1.0] - 2019-11-25 -### Added -- First release! :tada: - -[Unreleased]: https://github.com/hecrj/iced/compare/native-0.1.0...HEAD -[0.1.0]: https://github.com/hecrj/iced/releases/tag/native-0.1.0 diff --git a/native/src/lib.rs b/native/src/lib.rs index d17dd918..89612391 100644 --- a/native/src/lib.rs +++ b/native/src/lib.rs @@ -14,7 +14,7 @@ //! - A [`Widget`] trait, which is used to implement new widgets: from layout //! requirements to event and drawing logic. //! - A bunch of `Renderer` traits, meant to keep the crate renderer-agnostic. -//! - A [`window::Renderer`] trait, leveraging [`raw-window-handle`], which can be +//! - A [`window::Backend`] trait, leveraging [`raw-window-handle`], which can be //! implemented by graphical renderers that target _windows_. Window-based //! shells (like [`iced_winit`]) can use this trait to stay renderer-agnostic. //! @@ -31,7 +31,7 @@ //! [`druid`]: https://github.com/xi-editor/druid //! [`raw-window-handle`]: https://github.com/rust-windowing/raw-window-handle //! [`Widget`]: widget/trait.Widget.html -//! [`window::Renderer`]: window/trait.Renderer.html +//! [`window::Backend`]: window/trait.Backend.html //! [`UserInterface`]: struct.UserInterface.html //! [renderer]: renderer/index.html #![deny(missing_docs)] diff --git a/native/src/user_interface.rs b/native/src/user_interface.rs index 08914bed..5d9221e9 100644 --- a/native/src/user_interface.rs +++ b/native/src/user_interface.rs @@ -12,6 +12,13 @@ use std::hash::Hasher; /// charge of using this type in your system in any way you want. /// /// [`Layout`]: struct.Layout.html +/// +/// # Example +/// The [`integration` example] uses a [`UserInterface`] to integrate Iced in +/// an existing graphical application. +/// +/// [`integration` example]: https://github.com/hecrj/iced/tree/0.1/examples/integration +/// [`UserInterface`]: struct.UserInterface.html #[allow(missing_debug_implementations)] pub struct UserInterface<'a, Message, Renderer> { hash: u64, diff --git a/native/src/widget.rs b/native/src/widget.rs index 88f819c9..4453145b 100644 --- a/native/src/widget.rs +++ b/native/src/widget.rs @@ -76,6 +76,24 @@ use crate::{layout, Clipboard, Event, Hasher, Layout, Length, Point}; /// /// [`Widget`]: trait.Widget.html /// [`Element`]: ../struct.Element.html +/// +/// # Examples +/// The repository has some [examples] showcasing how to implement a custom +/// widget: +/// +/// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using +/// [`lyon`]. +/// - [`custom_widget`], a demonstration of how to build a custom widget that +/// draws a circle. +/// - [`geometry`], a custom widget showcasing how to draw geometry with the +/// `Mesh2D` primitive in [`iced_wgpu`]. +/// +/// [examples]: https://github.com/hecrj/iced/tree/0.1/examples +/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.1/examples/bezier_tool +/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.1/examples/custom_widget +/// [`geometry`]: https://github.com/hecrj/iced/tree/0.1/examples/geometry +/// [`lyon`]: https://github.com/nical/lyon +/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.1/wgpu pub trait Widget<Message, Renderer> where Renderer: crate::Renderer, @@ -139,12 +157,14 @@ where /// * a mutable `Message` list, allowing the [`Widget`] to produce /// new messages based on user interaction. /// * the `Renderer` + /// * a [`Clipboard`], if available /// /// By default, it does nothing. /// /// [`Event`]: ../enum.Event.html /// [`Widget`]: trait.Widget.html /// [`Layout`]: ../layout/struct.Layout.html + /// [`Clipboard`]: ../trait.Clipboard.html fn on_event( &mut self, _event: Event, diff --git a/native/src/widget/pane_grid.rs b/native/src/widget/pane_grid.rs index 2eca68d3..f6dd328e 100644 --- a/native/src/widget/pane_grid.rs +++ b/native/src/widget/pane_grid.rs @@ -1,6 +1,13 @@ //! Let your users split regions of your application and organize layout dynamically. //! //! [](https://gfycat.com/mixedflatjellyfish) +//! +//! # Example +//! The [`pane_grid` example] showcases how to use a [`PaneGrid`] with resizing, +//! drag and drop, and hotkey support. +//! +//! [`pane_grid` example]: https://github.com/hecrj/iced/tree/0.1/examples/pane_grid +//! [`PaneGrid`]: struct.PaneGrid.html mod axis; mod direction; mod node; @@ -59,12 +66,13 @@ use crate::{ /// /// let (mut state, _) = pane_grid::State::new(PaneState::SomePane); /// -/// let pane_grid = PaneGrid::new(&mut state, |pane, state, focus| { -/// match state { -/// PaneState::SomePane => Text::new("This is some pane"), -/// PaneState::AnotherKindOfPane => Text::new("This is another kind of pane"), -/// }.into() -/// }) +/// let pane_grid = +/// PaneGrid::new(&mut state, |pane, state, focus| { +/// match state { +/// PaneState::SomePane => Text::new("This is some pane"), +/// PaneState::AnotherKindOfPane => Text::new("This is another kind of pane"), +/// }.into() +/// }) /// .on_drag(Message::PaneDragged) /// .on_resize(Message::PaneResized); /// ``` diff --git a/native/src/widget/text_input.rs b/native/src/widget/text_input.rs index b4ba5afa..1c07e252 100644 --- a/native/src/widget/text_input.rs +++ b/native/src/widget/text_input.rs @@ -562,7 +562,7 @@ pub trait Renderer: crate::Renderer + Sized { /// Draws a [`TextInput`]. /// /// It receives: - /// - its bounds of the [`TextInput`] + /// - the bounds of the [`TextInput`] /// - the bounds of the text (i.e. the current value) /// - the cursor position /// - the placeholder to show when the value is empty diff --git a/src/application.rs b/src/application.rs index 551a9a79..689332f1 100644 --- a/src/application.rs +++ b/src/application.rs @@ -9,85 +9,89 @@ use crate::{window, Command, Element, Executor, Settings, Subscription}; /// - 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 +/// An [`Application`] 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: +/// When using an [`Application`] with the `debug` feature enabled, a debug view +/// can be toggled by pressing `F12`. +/// +/// [`Application`]: trait.Application.html +/// +/// # 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`]. +/// - [`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.1/examples +/// [`clock`]: https://github.com/hecrj/iced/tree/0.1/examples/clock +/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.1/examples/download_progress +/// [`events`]: https://github.com/hecrj/iced/tree/0.1/examples/events +/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.1/examples/pokedex +/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.1/examples/solar_system +/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.1/examples/stopwatch +/// [`todos`]: https://github.com/hecrj/iced/tree/0.1/examples/todos +/// [`Canvas`]: widget/canvas/struct.Canvas.html +/// [PokéAPI]: https://pokeapi.co/ +/// [`Subscription`]: type.Subscription.html +/// [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::{button, executor, Application, Button, Column, Command, Element, Settings, Text}; +/// use iced::{executor, Application, Command, Element, Settings, Text}; /// /// pub fn main() { -/// Counter::run(Settings::default()) +/// Hello::run(Settings::default()) /// } /// -/// #[derive(Default)] -/// struct Counter { -/// value: i32, -/// increment_button: button::State, -/// decrement_button: button::State, -/// } +/// struct Hello; /// -/// #[derive(Debug, Clone, Copy)] -/// enum Message { -/// IncrementPressed, -/// DecrementPressed, -/// } -/// -/// impl Application for Counter { +/// impl Application for Hello { /// type Executor = executor::Null; -/// type Message = Message; +/// type Message = (); /// type Flags = (); /// -/// fn new(_flags: ()) -> (Self, Command<Message>) { -/// (Self::default(), Command::none()) +/// fn new(_flags: ()) -> (Hello, Command<Self::Message>) { +/// (Hello, Command::none()) /// } /// /// fn title(&self) -> String { -/// String::from("A simple counter") +/// String::from("A cool application") /// } /// -/// fn update(&mut self, message: Message) -> Command<Message> { -/// match message { -/// Message::IncrementPressed => { -/// self.value += 1; -/// } -/// Message::DecrementPressed => { -/// self.value -= 1; -/// } -/// } -/// +/// fn update(&mut self, _message: Self::Message) -> Command<Self::Message> { /// 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() +/// 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 [`executor::Default`] can be a good starting point! + /// The [default executor] can be a good starting point! /// /// [`Executor`]: trait.Executor.html - /// [`executor::Default`]: executor/struct.Default.html + /// [default executor]: executor/struct.Default.html type Executor: Executor; /// The type of __messages__ your [`Application`] will produce. @@ -101,7 +105,7 @@ pub trait Application: Sized { type Flags; /// Initializes the [`Application`] with the flags provided to - /// [`run`] as part of the [`Settings`]: + /// [`run`] as part of the [`Settings`]. /// /// Here is where you should return the initial state of your app. /// @@ -172,8 +176,8 @@ pub trait Application: Sized { /// Runs the [`Application`]. /// - /// This method will take control of the current thread and __will NOT - /// return__. + /// On native platforms, 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. /// diff --git a/src/executor.rs b/src/executor.rs index 6c5425d1..59d59a5a 100644 --- a/src/executor.rs +++ b/src/executor.rs @@ -1,5 +1,5 @@ //! Choose your preferred executor to power your application. -pub use crate::common::{executor::Null, Executor}; +pub use crate::runtime::{executor::Null, Executor}; pub use platform::Default; @@ -166,13 +166,14 @@ //! 1. Draw the resulting user interface. //! //! # Usage -//! Take a look at the [`Application`] trait, which streamlines all the process -//! described above for you! +//! The [`Application`] and [`Sandbox`] traits should get you started quickly, +//! streamlining all the process described above! //! //! [Elm]: https://elm-lang.org/ //! [The Elm Architecture]: https://guide.elm-lang.org/architecture/ //! [examples]: https://github.com/hecrj/iced/tree/master/examples //! [`Application`]: trait.Application.html +//! [`Sandbox`]: trait.Sandbox.html #![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] @@ -198,12 +199,12 @@ pub use sandbox::Sandbox; pub use settings::Settings; #[cfg(not(target_arch = "wasm32"))] -use iced_winit as common; +use iced_winit as runtime; #[cfg(target_arch = "wasm32")] -use iced_web as common; +use iced_web as runtime; -pub use common::{ +pub use runtime::{ futures, Align, Background, Color, Command, Font, HorizontalAlignment, - Length, Point, Size, Space, Subscription, Vector, VerticalAlignment, + Length, Point, Size, Subscription, Vector, VerticalAlignment, }; diff --git a/src/sandbox.rs b/src/sandbox.rs index 4ea8de98..5233ebae 100644 --- a/src/sandbox.rs +++ b/src/sandbox.rs @@ -2,78 +2,89 @@ use crate::{executor, Application, Command, Element, Settings, Subscription}; /// A sandboxed [`Application`]. /// -/// A [`Sandbox`] is just an [`Application`] that cannot run any asynchronous -/// actions. +/// If you are a just getting started with the library, this trait offers a +/// simpler interface than [`Application`]. /// -/// If you do not need to leverage a [`Command`], you can use a [`Sandbox`] -/// instead of returning a [`Command::none`] everywhere. +/// Unlike an [`Application`], a [`Sandbox`] cannot run any asynchronous +/// actions. However, both traits are very similar and upgrading from a +/// [`Sandbox`] is very straightforward. +/// +/// Therefore, it is recommended to always start by implementing this trait and +/// upgrade only once you need to perform asynchronous work. /// /// [`Application`]: trait.Application.html /// [`Sandbox`]: trait.Sandbox.html /// [`Command`]: struct.Command.html /// [`Command::none`]: struct.Command.html#method.none /// -/// # Example -/// We can use a [`Sandbox`] to run the [`Counter` example we implemented -/// before](index.html#overview), instead of an [`Application`]. We just need -/// to remove the use of [`Command`]: +/// # Examples +/// [The repository has a bunch of examples] that use the [`Sandbox`] trait: +/// +/// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using +/// [`lyon`]. +/// - [`counter`], the classic counter example explained in [the overview]. +/// - [`custom_widget`], a demonstration of how to build a custom widget that +/// draws a circle. +/// - [`geometry`], a custom widget showcasing how to draw geometry with the +/// `Mesh2D` primitive in [`iced_wgpu`]. +/// - [`pane_grid`], a grid of panes that can be split, resized, and +/// reorganized. +/// - [`progress_bar`], a simple progress bar that can be filled by using a +/// slider. +/// - [`styling`], an example showcasing custom styling with a light and dark +/// theme. +/// - [`svg`], an application that renders the [Ghostscript Tiger] by leveraging +/// the [`Svg` widget]. +/// - [`tour`], a simple UI tour that can run both on native platforms and the +/// web! +/// +/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.1/examples +/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.1/examples/bezier_tool +/// [`counter`]: https://github.com/hecrj/iced/tree/0.1/examples/counter +/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.1/examples/custom_widget +/// [`geometry`]: https://github.com/hecrj/iced/tree/0.1/examples/geometry +/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.1/examples/pane_grid +/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.1/examples/progress_bar +/// [`styling`]: https://github.com/hecrj/iced/tree/0.1/examples/styling +/// [`svg`]: https://github.com/hecrj/iced/tree/0.1/examples/svg +/// [`tour`]: https://github.com/hecrj/iced/tree/0.1/examples/tour +/// [`lyon`]: https://github.com/nical/lyon +/// [the overview]: index.html#overview +/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.1/wgpu +/// [`Svg` widget]: widget/svg/struct.Svg.html +/// [Ghostscript Tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg +/// +/// ## A simple "Hello, world!" +/// +/// If you just want to get started, here is a simple [`Sandbox`] that +/// says "Hello, world!": /// /// ```no_run -/// use iced::{button, Button, Column, Element, Sandbox, Settings, Text}; +/// use iced::{Element, Sandbox, Settings, Text}; /// /// pub fn main() { -/// Counter::run(Settings::default()) -/// } -/// -/// #[derive(Default)] -/// struct Counter { -/// value: i32, -/// increment_button: button::State, -/// decrement_button: button::State, +/// Hello::run(Settings::default()) /// } /// -/// #[derive(Debug, Clone, Copy)] -/// enum Message { -/// IncrementPressed, -/// DecrementPressed, -/// } +/// struct Hello; /// -/// impl Sandbox for Counter { -/// type Message = Message; +/// impl Sandbox for Hello { +/// type Message = (); /// -/// fn new() -> Self { -/// Self::default() +/// fn new() -> Hello { +/// Hello /// } /// /// fn title(&self) -> String { -/// String::from("A simple counter") +/// String::from("A cool application") /// } /// -/// fn update(&mut self, message: Message) { -/// match message { -/// Message::IncrementPressed => { -/// self.value += 1; -/// } -/// Message::DecrementPressed => { -/// self.value -= 1; -/// } -/// } +/// fn update(&mut self, _message: Self::Message) { +/// // This application has no interactions /// } /// -/// 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() +/// fn view(&mut self) -> Element<Self::Message> { +/// Text::new("Hello, world!").into() /// } /// } /// ``` @@ -115,8 +126,8 @@ pub trait Sandbox { /// Runs the [`Sandbox`]. /// - /// This method will take control of the current thread and __will NOT - /// return__. + /// On native platforms, 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. /// diff --git a/src/settings.rs b/src/settings.rs index f36ec85f..ea969617 100644 --- a/src/settings.rs +++ b/src/settings.rs @@ -13,7 +13,7 @@ pub struct Settings<Flags> { /// The data needed to initialize an [`Application`]. /// - /// [`Application`]: trait.Application.html + /// [`Application`]: ../trait.Application.html pub flags: Flags, /// The bytes of the font that will be used by default. @@ -26,9 +26,11 @@ pub struct Settings<Flags> { /// primitives. /// /// Enabling it can produce a smoother result in some widgets, like the - /// `Canvas`, at a performance cost. + /// [`Canvas`], at a performance cost. /// /// By default, it is disabled. + /// + /// [`Canvas`]: ../widget/canvas/struct.Canvas.html pub antialiasing: bool, } diff --git a/src/widget.rs b/src/widget.rs index 91ea1ed4..758dc930 100644 --- a/src/widget.rs +++ b/src/widget.rs @@ -30,7 +30,7 @@ mod platform { pub use iced_winit::svg::{Handle, Svg}; } - pub use iced_winit::Text; + pub use iced_winit::{Space, Text}; #[doc(no_inline)] pub use { @@ -40,6 +40,10 @@ mod platform { text_input::TextInput, }; + #[cfg(feature = "canvas")] + #[doc(no_inline)] + pub use canvas::Canvas; + /// A container that distributes its contents vertically. /// /// This is an alias of an `iced_native` column with a default `Renderer`. diff --git a/web/CHANGELOG.md b/web/CHANGELOG.md deleted file mode 100644 index ed02519a..00000000 --- a/web/CHANGELOG.md +++ /dev/null @@ -1,19 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] -### Changed -- `Button::background` takes an `Into<Background>` now instead of a `Background`. - -### Fixed -- Render not being scheduled after `Command` futures finishing. - -## [0.1.0] - 2019-11-25 -### Added -- First release! :tada: - -[Unreleased]: https://github.com/hecrj/iced/compare/web-0.1.0...HEAD -[0.1.0]: https://github.com/hecrj/iced/releases/tag/web-0.1.0 diff --git a/web/README.md b/web/README.md index 83d1500f..1b818ab6 100644 --- a/web/README.md +++ b/web/README.md @@ -50,6 +50,7 @@ Once the example is compiled, we need to create an `.html` file to load our appl <html> <head> <meta http-equiv="Content-type" content="text/html; charset=utf-8"/> + <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Tour - Iced</title> </head> <body> diff --git a/web/src/lib.rs b/web/src/lib.rs index a0b39c4a..29120dbf 100644 --- a/web/src/lib.rs +++ b/web/src/lib.rs @@ -23,8 +23,8 @@ //! //! ```bash //! cd examples -//! cargo build --example tour --target wasm32-unknown-unknown -//! wasm-bindgen ../target/wasm32-unknown-unknown/debug/examples/tour.wasm --out-dir tour --web +//! cargo build --package tour --target wasm32-unknown-unknown +//! wasm-bindgen ../target/wasm32-unknown-unknown/debug/tour.wasm --out-dir tour --web //! ``` //! //! Then, we need to create an `.html` file to load our application: @@ -34,6 +34,7 @@ //! <html> //! <head> //! <meta http-equiv="Content-type" content="text/html; charset=utf-8"/> +//! <meta name="viewport" content="width=device-width, initial-scale=1"> //! <title>Tour - Iced</title> //! </head> //! <body> diff --git a/wgpu/CHANGELOG.md b/wgpu/CHANGELOG.md deleted file mode 100644 index f9708308..00000000 --- a/wgpu/CHANGELOG.md +++ /dev/null @@ -1,14 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -## [0.1.0] - 2019-11-25 -### Added -- First release! :tada: - -[Unreleased]: https://github.com/hecrj/iced/compare/wgpu-0.1.0...HEAD -[0.1.0]: https://github.com/hecrj/iced/releases/tag/wgpu-0.1.0 diff --git a/wgpu/README.md b/wgpu/README.md index 38c6ddb6..cd80379e 100644 --- a/wgpu/README.md +++ b/wgpu/README.md @@ -11,8 +11,9 @@ Currently, `iced_wgpu` supports the following primitives: - Text, which is rendered using [`wgpu_glyph`]. No shaping at all. - Quads or rectangles, with rounded borders and a solid background color. -- Images, lazily loaded from the filesystem. - Clip areas, useful to implement scrollables or hide overflowing content. +- Images and SVG, loaded from memory or the file system. +- Meshes of triangles, useful to draw geometry freely.  diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index 4e0cbc60..f00c7d2c 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -11,8 +11,9 @@ //! Currently, `iced_wgpu` supports the following primitives: //! - Text, which is rendered using [`wgpu_glyph`]. No shaping at all. //! - Quads or rectangles, with rounded borders and a solid background color. -//! - Images, lazily loaded from the filesystem. //! - Clip areas, useful to implement scrollables or hide overflowing content. +//! - Images and SVG, loaded from memory or the file system. +//! - Meshes of triangles, useful to draw geometry freely. //! //! [Iced]: https://github.com/hecrj/iced //! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native diff --git a/wgpu/src/widget/canvas.rs b/wgpu/src/widget/canvas.rs index 3a9605c9..325f90ce 100644 --- a/wgpu/src/widget/canvas.rs +++ b/wgpu/src/widget/canvas.rs @@ -33,11 +33,61 @@ pub use text::Text; /// A widget capable of drawing 2D graphics. /// /// A [`Canvas`] may contain multiple layers. A [`Layer`] is drawn using the -/// painter's algorithm. In other words, layers will be drawn on top of each in -/// the same order they are pushed into the [`Canvas`]. +/// painter's algorithm. In other words, layers will be drawn on top of each +/// other in the same order they are pushed into the [`Canvas`]. /// /// [`Canvas`]: struct.Canvas.html /// [`Layer`]: layer/trait.Layer.html +/// +/// # Examples +/// The repository has a couple of [examples] showcasing how to use a +/// [`Canvas`]: +/// +/// - [`clock`], an application that uses the [`Canvas`] widget to draw a clock +/// and its hands to display the current time. +/// - [`solar_system`], an animated solar system drawn using the [`Canvas`] widget +/// and showcasing how to compose different transforms. +/// +/// [examples]: https://github.com/hecrj/iced/tree/0.1/examples +/// [`clock`]: https://github.com/hecrj/iced/tree/0.1/examples/clock +/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.1/examples/solar_system +/// +/// ## Drawing a simple circle +/// If you want to get a quick overview, here's how we can draw a simple circle: +/// +/// ```no_run +/// # mod iced { +/// # pub use iced_wgpu::canvas; +/// # pub use iced_native::Color; +/// # } +/// use iced::canvas::{self, layer, Canvas, Drawable, Fill, Frame, Path}; +/// use iced::Color; +/// +/// // First, we define the data we need for drawing +/// #[derive(Debug)] +/// struct Circle { +/// radius: f32, +/// } +/// +/// // Then, we implement the `Drawable` trait +/// impl Drawable for Circle { +/// fn draw(&self, frame: &mut Frame) { +/// // We create a `Path` representing a simple circle +/// let circle = Path::new(|p| p.circle(frame.center(), self.radius)); +/// +/// // And fill it with some color +/// frame.fill(&circle, Fill::Color(Color::BLACK)); +/// } +/// } +/// +/// // We can use a `Cache` to avoid unnecessary re-tessellation +/// let cache: layer::Cache<Circle> = layer::Cache::new(); +/// +/// // Finally, we simply provide the data to our `Cache` and push the resulting +/// // layer into a `Canvas` +/// let canvas = Canvas::new() +/// .push(cache.with(&Circle { radius: 50.0 })); +/// ``` #[derive(Debug)] pub struct Canvas<'a> { width: Length, diff --git a/wgpu/src/widget/canvas/layer/cache.rs b/wgpu/src/widget/canvas/layer/cache.rs index f7002459..20a095bd 100644 --- a/wgpu/src/widget/canvas/layer/cache.rs +++ b/wgpu/src/widget/canvas/layer/cache.rs @@ -12,7 +12,7 @@ use std::{cell::RefCell, marker::PhantomData, sync::Arc}; /// change or it is explicitly cleared. /// /// [`Layer`]: ../trait.Layer.html -/// [`Cached`]: struct.Cached.html +/// [`Cache`]: struct.Cache.html #[derive(Debug)] pub struct Cache<T: Drawable> { input: PhantomData<T>, diff --git a/wgpu/src/widget/canvas/path.rs b/wgpu/src/widget/canvas/path.rs index 15c2e853..e7ff47f3 100644 --- a/wgpu/src/widget/canvas/path.rs +++ b/wgpu/src/widget/canvas/path.rs @@ -3,6 +3,7 @@ pub mod arc; mod builder; +#[doc(no_inline)] pub use arc::Arc; pub use builder::Builder; diff --git a/wgpu/src/widget/pane_grid.rs b/wgpu/src/widget/pane_grid.rs index 7bc2f7c5..578e8960 100644 --- a/wgpu/src/widget/pane_grid.rs +++ b/wgpu/src/widget/pane_grid.rs @@ -1,6 +1,13 @@ //! Let your users split regions of your application and organize layout dynamically. //! //! [](https://gfycat.com/mixedflatjellyfish) +//! +//! # Example +//! The [`pane_grid` example] showcases how to use a [`PaneGrid`] with resizing, +//! drag and drop, and hotkey support. +//! +//! [`pane_grid` example]: https://github.com/hecrj/iced/tree/0.1/examples/pane_grid +//! [`PaneGrid`]: type.PaneGrid.html use crate::Renderer; pub use iced_native::pane_grid::{ diff --git a/winit/CHANGELOG.md b/winit/CHANGELOG.md deleted file mode 100644 index 1289a45a..00000000 --- a/winit/CHANGELOG.md +++ /dev/null @@ -1,14 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -## [0.1.0-alpha] - 2019-11-25 -### Added -- First release! :tada: - -[Unreleased]: https://github.com/hecrj/iced/compare/winit-0.1.0-alpha...HEAD -[0.1.0-alpha]: https://github.com/hecrj/iced/releases/tag/winit-0.1.0-alpha diff --git a/winit/Cargo.toml b/winit/Cargo.toml index ca2018c7..a3b1613d 100644 --- a/winit/Cargo.toml +++ b/winit/Cargo.toml @@ -19,7 +19,7 @@ window_clipboard = "0.1" log = "0.4" [dependencies.iced_native] -version = "0.1.0-alpha" +version = "0.1.0" path = "../native" [target.'cfg(target_os = "windows")'.dependencies.winapi] diff --git a/winit/src/application.rs b/winit/src/application.rs index d5f957bf..b974711c 100644 --- a/winit/src/application.rs +++ b/winit/src/application.rs @@ -12,6 +12,9 @@ use crate::{ /// /// An [`Application`](trait.Application.html) can execute asynchronous actions /// by returning a [`Command`](struct.Command.html) in some of its methods. +/// +/// When using an [`Application`] with the `debug` feature enabled, a debug view +/// can be toggled by pressing `F12`. pub trait Application: Sized { /// The graphics backend to use to draw the [`Application`]. /// @@ -34,7 +37,7 @@ pub trait Application: Sized { type Flags; /// Initializes the [`Application`] with the flags provided to - /// [`run`] as part of the [`Settings`]: + /// [`run`] as part of the [`Settings`]. /// /// Here is where you should return the initial state of your app. /// @@ -100,8 +103,8 @@ pub trait Application: Sized { /// Runs the [`Application`] with the provided [`Settings`]. /// - /// This method will take control of the current thread and __will NOT - /// return__. + /// On native platforms, 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. /// diff --git a/winit/src/conversion.rs b/winit/src/conversion.rs index debaf535..eaa26ace 100644 --- a/winit/src/conversion.rs +++ b/winit/src/conversion.rs @@ -90,7 +90,8 @@ pub fn window_event( /// Converts a [`Mode`] to a [`winit`] fullscreen mode. /// -/// [`Mode`]: +/// [`Mode`]: ../enum.Mode.html +/// [`winit`]: https://github.com/rust-windowing/winit pub fn fullscreen( monitor: winit::monitor::MonitorHandle, mode: Mode, |