diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/lib.rs | 415 |
1 files changed, 286 insertions, 129 deletions
@@ -1,170 +1,327 @@ -//! Iced is a cross-platform GUI library focused on simplicity and type-safety. +//! iced is a cross-platform GUI library focused on simplicity and type-safety. //! Inspired by [Elm]. //! -//! # Features -//! * Simple, easy-to-use, batteries-included API -//! * Type-safe, reactive programming model -//! * [Cross-platform support] (Windows, macOS, Linux, and the Web) -//! * Responsive layout -//! * Built-in widgets (including [text inputs], [scrollables], and more!) -//! * Custom widget support (create your own!) -//! * [Debug overlay with performance metrics] -//! * First-class support for async actions (use futures!) -//! * [Modular ecosystem] split into reusable parts: -//! * A [renderer-agnostic native runtime] enabling integration with existing -//! systems -//! * A [built-in renderer] supporting Vulkan, Metal, DX11, and DX12 -//! * A [windowing shell] -//! * A [web runtime] leveraging the DOM -//! -//! Check out the [repository] and the [examples] for more details! -//! -//! [Cross-platform support]: https://github.com/iced-rs/iced/blob/master/docs/images/todos_desktop.jpg?raw=true -//! [text inputs]: https://iced.rs/examples/text_input.mp4 -//! [scrollables]: https://iced.rs/examples/scrollable.mp4 -//! [Debug overlay with performance metrics]: https://iced.rs/examples/debug.mp4 -//! [Modular ecosystem]: https://github.com/iced-rs/iced/blob/master/ECOSYSTEM.md -//! [renderer-agnostic native runtime]: https://github.com/iced-rs/iced/tree/0.12/runtime -//! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs -//! [built-in renderer]: https://github.com/iced-rs/iced/tree/0.12/wgpu -//! [windowing shell]: https://github.com/iced-rs/iced/tree/0.12/winit -//! [`dodrio`]: https://github.com/fitzgen/dodrio -//! [web runtime]: https://github.com/iced-rs/iced_web -//! [examples]: https://github.com/iced-rs/iced/tree/0.12/examples -//! [repository]: https://github.com/iced-rs/iced -//! -//! # Overview -//! Inspired by [The Elm Architecture], Iced expects you to split user -//! interfaces into four different concepts: -//! -//! * __State__ — the state of your application -//! * __Messages__ — user interactions or meaningful events that you care -//! about -//! * __View logic__ — a way to display your __state__ as widgets that -//! may produce __messages__ on user interaction -//! * __Update logic__ — a way to react to __messages__ and update your -//! __state__ -//! -//! We can build something to see how this works! Let's say we want a simple -//! counter that can be incremented and decremented using two buttons. -//! -//! We start by modelling the __state__ of our application: +//! # Disclaimer +//! iced is __experimental__ software. If you expect the documentation to hold your hand +//! as you learn the ropes, you are in for a frustrating experience. //! +//! The library leverages Rust to its full extent: ownership, borrowing, lifetimes, futures, +//! streams, first-class functions, trait bounds, closures, and more. This documentation +//! is not meant to teach you any of these. Far from it, it will assume you have __mastered__ +//! all of them. +//! +//! Furthermore—just like Rust—iced is very unforgiving. It will not let you easily cut corners. +//! The type signatures alone can be used to learn how to use most of the library. +//! Everything is connected. +//! +//! Therefore, iced is easy to learn for __advanced__ Rust programmers; but plenty of patient +//! beginners have learned it and had a good time with it. Since it leverages a lot of what +//! Rust has to offer in a type-safe way, it can be a great way to discover Rust itself. +//! +//! If you don't like the sound of that, you expect to be spoonfed, or you feel frustrated +//! and struggle to use the library; then I recommend you to wait patiently until [the book] +//! is finished. +//! +//! [the book]: https://book.iced.rs +//! +//! # The Pocket Guide +//! Start by calling [`run`]: +//! +//! ```rust,no_run +//! pub fn main() -> iced::Result { +//! iced::run("A cool counter", update, view) +//! } +//! # fn update(state: &mut (), message: ()) {} +//! # fn view(state: &()) -> iced::Element<()> { iced::widget::text("").into() } //! ``` -//! #[derive(Default)] -//! struct Counter { -//! // The counter value -//! value: i32, +//! +//! Define an `update` function to __change__ your state: +//! +//! ```rust +//! fn update(counter: &mut u64, message: Message) { +//! match message { +//! Message::Increment => *counter += 1, +//! } //! } +//! # #[derive(Clone)] +//! # enum Message { Increment } //! ``` //! -//! Next, we need to define the possible user interactions of our counter: -//! the button presses. These interactions are our __messages__: +//! Define a `view` function to __display__ your state: +//! +//! ```rust +//! use iced::widget::{button, text}; +//! use iced::Element; //! +//! fn view(counter: &u64) -> Element<Message> { +//! button(text(counter)).on_press(Message::Increment).into() +//! } +//! # #[derive(Clone)] +//! # enum Message { Increment } //! ``` -//! #[derive(Debug, Clone, Copy)] -//! pub enum Message { +//! +//! And create a `Message` enum to __connect__ `view` and `update` together: +//! +//! ```rust +//! #[derive(Debug, Clone)] +//! enum Message { //! Increment, -//! Decrement, //! } //! ``` //! -//! Now, let's show the actual counter by putting it all together in our -//! __view logic__: +//! ## Custom State +//! You can define your own struct for your state: //! +//! ```rust +//! #[derive(Default)] +//! struct Counter { +//! value: u64, +//! } //! ``` -//! # struct Counter { -//! # // The counter value -//! # value: i32, -//! # } -//! # -//! # #[derive(Debug, Clone, Copy)] -//! # pub enum Message { -//! # Increment, -//! # Decrement, -//! # } -//! # -//! use iced::widget::{button, column, text, Column}; -//! -//! impl Counter { -//! pub fn view(&self) -> Column<Message> { -//! // We use a column: a simple vertical layout -//! column![ -//! // The increment button. We tell it to produce an -//! // `Increment` message when pressed -//! button("+").on_press(Message::Increment), //! -//! // We show the value of the counter here -//! text(self.value).size(50), +//! But you have to change `update` and `view` accordingly: //! -//! // The decrement button. We tell it to produce a -//! // `Decrement` message when pressed -//! button("-").on_press(Message::Decrement), -//! ] +//! ```rust +//! # struct Counter { value: u64 } +//! # #[derive(Clone)] +//! # enum Message { Increment } +//! # use iced::widget::{button, text}; +//! # use iced::Element; +//! fn update(counter: &mut Counter, message: Message) { +//! match message { +//! Message::Increment => counter.value += 1, //! } //! } +//! +//! fn view(counter: &Counter) -> Element<Message> { +//! button(text(counter.value)).on_press(Message::Increment).into() +//! } //! ``` //! -//! Finally, we need to be able to react to any produced __messages__ and change -//! our __state__ accordingly in our __update logic__: +//! ## Widgets and Elements +//! The `view` function must return an [`Element`]. An [`Element`] is just a generic [`widget`]. +//! +//! The [`widget`] module contains a bunch of functions to help you build +//! and use widgets. +//! +//! Widgets are configured using the builder pattern: //! +//! ```rust +//! # struct Counter { value: u64 } +//! # #[derive(Clone)] +//! # enum Message { Increment } +//! use iced::widget::{button, column, text}; +//! use iced::Element; +//! +//! fn view(counter: &Counter) -> Element<Message> { +//! column![ +//! text(counter.value).size(20), +//! button("Increment").on_press(Message::Increment), +//! ] +//! .spacing(10) +//! .into() +//! } //! ``` -//! # struct Counter { -//! # // The counter value -//! # value: i32, -//! # } -//! # -//! # #[derive(Debug, Clone, Copy)] -//! # pub enum Message { -//! # Increment, -//! # Decrement, -//! # } -//! impl Counter { -//! // ... //! -//! pub fn update(&mut self, message: Message) { -//! match message { -//! Message::Increment => { -//! self.value += 1; -//! } -//! Message::Decrement => { -//! self.value -= 1; -//! } -//! } -//! } +//! A widget can be turned into an [`Element`] by calling `into`. +//! +//! Widgets and elements are generic over the message type they produce. The +//! [`Element`] returned by `view` must have the same `Message` type as +//! your `update`. +//! +//! ## Layout +//! There is no unified layout system in iced. Instead, each widget implements +//! its own layout strategy. +//! +//! Generally, building your layout will consist in using a combination of +//! [rows], [columns], and [containers]: +//! +//! ```rust +//! # struct State; +//! # enum Message {} +//! use iced::widget::{column, container, row}; +//! use iced::{Fill, Element}; +//! +//! fn view(state: &State) -> Element<Message> { +//! container( +//! column![ +//! "Top", +//! row!["Left", "Right"].spacing(10), +//! "Bottom" +//! ] +//! .spacing(10) +//! ) +//! .padding(10) +//! .center_x(Fill) +//! .center_y(Fill) +//! .into() //! } //! ``` //! -//! And that's everything! We just wrote a whole user interface. Let's run it: +//! Rows and columns lay out their children horizontally and vertically, +//! respectively. [Spacing] can be easily added between elements. +//! +//! Containers position or align a single widget inside their bounds. +//! +//! [rows]: widget::Row +//! [columns]: widget::Column +//! [containers]: widget::Container +//! [Spacing]: widget::Column::spacing +//! +//! ## Sizing +//! The width and height of widgets can generally be defined using a [`Length`]. +//! +//! - [`Fill`] will make the widget take all the available space in a given axis. +//! - [`Shrink`] will make the widget use its intrinsic size. //! -//! ```no_run +//! Most widgets use a [`Shrink`] sizing strategy by default, but will inherit +//! a [`Fill`] strategy from their children. +//! +//! A fixed numeric [`Length`] in [`Pixels`] can also be used: +//! +//! ```rust +//! # struct State; +//! # enum Message {} +//! use iced::widget::container; +//! use iced::Element; +//! +//! fn view(state: &State) -> Element<Message> { +//! container("I am 300px tall!").height(300).into() +//! } +//! ``` +//! +//! ## Theming +//! The default [`Theme`] of an application can be changed by defining a `theme` +//! function and leveraging the [`Application`] builder, instead of directly +//! calling [`run`]: +//! +//! ```rust,no_run //! # #[derive(Default)] -//! # struct Counter; -//! # impl Counter { -//! # fn update(&mut self, _message: ()) {} -//! # fn view(&self) -> iced::Element<()> { unimplemented!() } -//! # } -//! # -//! fn main() -> iced::Result { -//! iced::run("A cool counter", Counter::update, Counter::view) +//! # struct State; +//! use iced::Theme; +//! +//! pub fn main() -> iced::Result { +//! iced::application("A cool application", update, view) +//! .theme(theme) +//! .run() +//! } +//! +//! fn theme(state: &State) -> Theme { +//! Theme::TokyoNight +//! } +//! # fn update(state: &mut State, message: ()) {} +//! # fn view(state: &State) -> iced::Element<()> { iced::widget::text("").into() } +//! ``` +//! +//! The `theme` function takes the current state of the application, allowing the +//! returned [`Theme`] to be completely dynamic—just like `view`. +//! +//! There are a bunch of built-in [`Theme`] variants at your disposal, but you can +//! also [create your own](Theme::custom). +//! +//! ## Styling +//! As with layout, iced does not have a unified styling system. However, all +//! of the built-in widgets follow the same styling approach. +//! +//! The appearance of a widget can be changed by calling its `style` method: +//! +//! ```rust +//! # struct State; +//! # enum Message {} +//! use iced::widget::container; +//! use iced::Element; +//! +//! fn view(state: &State) -> Element<Message> { +//! container("I am a rounded box!").style(container::rounded_box).into() +//! } +//! ``` +//! +//! The `style` method of a widget takes a closure that, given the current active +//! [`Theme`], returns the widget style: +//! +//! ```rust +//! # struct State; +//! # #[derive(Clone)] +//! # enum Message {} +//! use iced::widget::button; +//! use iced::{Element, Theme}; +//! +//! fn view(state: &State) -> Element<Message> { +//! button("I am a styled button!").style(|theme: &Theme, status| { +//! let palette = theme.extended_palette(); +//! +//! match status { +//! button::Status::Active => { +//! button::Style::default() +//! .with_background(palette.success.strong.color) +//! } +//! _ => button::primary(theme, status), +//! } +//! }) +//! .into() //! } //! ``` //! -//! Iced will automatically: +//! Widgets that can be in multiple different states will also provide the closure +//! with some [`Status`], allowing you to use a different style for each state. +//! +//! You can extract the [`Palette`] colors of a [`Theme`] with the [`palette`] or +//! [`extended_palette`] methods. //! -//! 1. Take the result of our __view logic__ and layout its widgets. -//! 1. Process events from our system and produce __messages__ for our -//! __update logic__. -//! 1. Draw the resulting user interface. +//! Most widgets provide styling functions for your convenience in their respective modules; +//! like [`container::rounded_box`], [`button::primary`], or [`text::danger`]. //! -//! # Usage -//! Use [`run`] or the [`application`] builder. +//! [`Status`]: widget::button::Status +//! [`palette`]: Theme::palette +//! [`extended_palette`]: Theme::extended_palette +//! [`container::rounded_box`]: widget::container::rounded_box +//! [`button::primary`]: widget::button::primary +//! [`text::danger`]: widget::text::danger +//! +//! ## Concurrent Tasks +//! The `update` function can _optionally_ return a [`Task`]. +//! +//! A [`Task`] can be leveraged to perform asynchronous work, like running a +//! future or a stream: +//! +//! ```rust +//! # #[derive(Clone)] +//! # struct Weather; +//! use iced::Task; +//! +//! struct State { +//! weather: Option<Weather>, +//! } +//! +//! enum Message { +//! FetchWeather, +//! WeatherFetched(Weather), +//! } +//! +//! fn update(state: &mut State, message: Message) -> Task<Message> { +//! match message { +//! Message::FetchWeather => Task::perform( +//! fetch_weather(), +//! Message::WeatherFetched, +//! ), +//! Message::WeatherFetched(weather) => { +//! state.weather = Some(weather); +//! +//! Task::none() +//! } +//! } +//! } +//! +//! async fn fetch_weather() -> Weather { +//! // ... +//! # unimplemented!() +//! } +//! ``` //! //! [Elm]: https://elm-lang.org/ -//! [The Elm Architecture]: https://guide.elm-lang.org/architecture/ //! [`application`]: application() #![doc( - html_logo_url = "https://raw.githubusercontent.com/iced-rs/iced/9ab6923e943f784985e9ef9ca28b10278297225d/docs/logo.svg" + html_logo_url = "https://raw.githubusercontent.com/iced-rs/iced/bdf0430880f5c29443f5f0a0ae4895866dfef4c6/docs/logo.svg" )] #![cfg_attr(docsrs, feature(doc_auto_cfg))] #![cfg_attr(docsrs, feature(doc_cfg))] |