Merge pull request #252 from hecrj/improvement/documentation
Update and improve documentation
This commit is contained in:
commit
3aafd2c1f7
@ -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/
|
||||
|
@ -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
|
@ -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);
|
||||
|
@ -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 {
|
||||
|
@ -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>>,
|
||||
}
|
||||
|
@ -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()
|
||||
}
|
||||
|
@ -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`].
|
||||
|
@ -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()
|
||||
|
@ -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
|
@ -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)]
|
||||
|
@ -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,
|
||||
|
@ -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,
|
||||
|
@ -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);
|
||||
/// ```
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
///
|
||||
|
@ -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;
|
||||
|
||||
|
13
src/lib.rs
13
src/lib.rs
@ -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,
|
||||
};
|
||||
|
115
src/sandbox.rs
115
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())
|
||||
/// 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 Sandbox for Hello {
|
||||
/// type Message = ();
|
||||
///
|
||||
/// impl Sandbox for Counter {
|
||||
/// type Message = 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.
|
||||
///
|
||||
|
@ -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,
|
||||
}
|
||||
|
||||
|
@ -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`.
|
||||
|
@ -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
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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
|
@ -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.
|
||||
|
||||

|
||||
|
||||
|
@ -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
|
||||
|
@ -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,
|
||||
|
@ -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>,
|
||||
|
@ -3,6 +3,7 @@ pub mod arc;
|
||||
|
||||
mod builder;
|
||||
|
||||
#[doc(no_inline)]
|
||||
pub use arc::Arc;
|
||||
pub use builder::Builder;
|
||||
|
||||
|
@ -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::{
|
||||
|
@ -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
|
@ -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]
|
||||
|
@ -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.
|
||||
///
|
||||
|
@ -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,
|
||||
|
Loading…
x
Reference in New Issue
Block a user