reivilibre/iced-mobile
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Write documentation for iced_core

Browse Source
This commit is contained in:
Héctor Ramón Jiménez 2019-11-18 07:16:19 +01:00
parent 63dbf078fe
commit d3553adf27
16 changed files with 216 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
core/src/background.rs
View File

@ -1,7 +1,9 @@
use crate::Color;
/// The background of some element.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Background {
/// A solid color
Color(Color),
// TODO: Add gradient and image variants
}

3
core/src/color.rs
View File

@ -25,6 +25,9 @@ impl Color {
a: 1.0,
};
/// Converts the [`Color`] into its linear values.
///
/// [`Color`]: struct.Color.html
pub fn into_linear(self) -> [f32; 4] {
// As described in:
// https://en.wikipedia.org/wiki/SRGB#The_reverse_transformation

23
core/src/command.rs
View File

@ -1,16 +1,30 @@
use futures::future::{BoxFuture, Future, FutureExt};
/// A collection of async operations.
///
/// You should be able to turn a future easily into a [`Command`], eiter by
/// using the `From` trait or [`Command::perform`].
///
/// [`Command`]: struct.Command.html
pub struct Command<T> {
futures: Vec<BoxFuture<'static, T>>,
}
impl<T> Command<T> {
/// Creates an empty [`Command`].
///
/// In other words, a [`Command`] that does nothing.
///
/// [`Command`]: struct.Command.html
pub fn none() -> Self {
Self {
futures: Vec::new(),
}
}
/// Creates a [`Command`] that performs the action of the given future.
///
/// [`Command`]: struct.Command.html
pub fn perform<A>(
future: impl Future<Output = T> + 'static + Send,
f: impl Fn(T) -> A + 'static + Send,
@ -20,12 +34,21 @@ impl<T> Command<T> {
}
}
/// Creates a [`Command`] that performs the actions of all the givens
/// futures.
///
/// Once this command is run, all the futures will be exectued at once.
///
/// [`Command`]: struct.Command.html
pub fn batch(commands: impl Iterator<Item = Command<T>>) -> Self {
Self {
futures: commands.flat_map(|command| command.futures).collect(),
}
}
/// Converts a [`Command`] into its underlying list of futures.
///
/// [`Command`]: struct.Command.html
pub fn futures(self) -> Vec<BoxFuture<'static, T>> {
self.futures
}

10
core/src/font.rs
View File

@ -1,8 +1,18 @@
/// A font.
#[derive(Debug, Clone, Copy)]
pub enum Font {
/// The default font.
///
/// This is normally a font configured in a renderer or loaded from the
/// system.
Default,
/// An external font.
External {
/// The name of the external font
name: &'static str,
/// The bytes of the external font
bytes: &'static [u8],
},
}

12
core/src/length.rs
View File

@ -1,12 +1,24 @@
/// The strategy used to fill space in a specific dimension.
#[derive(Debug, Clone, Copy, PartialEq, Hash)]
pub enum Length {
/// Fill all the remaining space
Fill,
/// Fill the least amount of space
Shrink,
/// Fill a fixed amount of space
Units(u16),
}
impl Length {
/// Returns the _fill factor_ of the [`Length`].
///
/// The _fill factor_ is a relative unit describing how much of the
/// remaining space should be filled when compared to other elements. It
/// is only meant to be used by layout engines.
///
/// [`Length`]: enum.Length.html
pub fn fill_factor(&self) -> u16 {
match self {
Length::Fill => 1,

24
core/src/lib.rs
View File

@ -1,10 +1,22 @@
//! The core library of [Iced].
//!
//! This library holds basic types that can be reused and re-exported in
//! different runtime implementations. For instance, both [`iced_native`] and
//! [`iced_web`] are built on top of `iced_core`.
//!
//! [Iced]: https://github.com/hecrj/iced
//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
//! [`iced_web`]: https://github.com/hecrj/iced/tree/master/web
#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#![deny(unused_results)]
#![deny(unsafe_code)]
#![deny(rust_2018_idioms)]
pub mod widget;
mod align;
mod background;
mod color;
#[cfg(feature = "command")]
mod command;
mod font;
mod length;
mod point;
@ -14,11 +26,15 @@ mod vector;
pub use align::Align;
pub use background::Background;
pub use color::Color;
#[cfg(feature = "command")]
pub use command::Command;
pub use font::Font;
pub use length::Length;
pub use point::Point;
pub use rectangle::Rectangle;
pub use vector::Vector;
pub use widget::*;
#[cfg(feature = "command")]
mod command;
#[cfg(feature = "command")]
pub use command::Command;

7
core/src/vector.rs
View File

@ -1,7 +1,14 @@
/// A 2D vector.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Vector<T = f32> {
/// The X component of the [`Vector`]
///
/// [`Vector`]: struct.Vector.html
pub x: T,
/// The Y component of the [`Vector`]
///
/// [`Vector`]: struct.Vector.html
pub y: T,
}

50
core/src/widget/button.rs
View File

@ -8,40 +8,22 @@
use crate::{Background, Length};
/// A generic widget that produces a message when clicked.
#[allow(missing_docs)]
#[derive(Debug)]
pub struct Button<'a, Message, Element> {
/// The current state of the button
pub state: &'a mut State,
pub content: Element,
/// The message to produce when the button is pressed
pub on_press: Option<Message>,
pub width: Length,
pub min_width: u32,
pub padding: u16,
pub background: Option<Background>,
pub border_radius: u16,
}
impl<'a, Message, Element> std::fmt::Debug for Button<'a, Message, Element>
where
Message: std::fmt::Debug,
{
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Button")
.field("state", &self.state)
.field("on_press", &self.on_press)
.finish()
}
}
impl<'a, Message, Element> Button<'a, Message, Element> {
/// Creates a new [`Button`] with some local [`State`] and the given label.
/// Creates a new [`Button`] with some local [`State`] and the given
/// content.
///
/// [`Button`]: struct.Button.html
/// [`State`]: struct.State.html
@ -69,21 +51,34 @@ impl<'a, Message, Element> Button<'a, Message, Element> {
self
}
/// Sets the minimum width of the [`Button`].
///
/// [`Button`]: struct.Button.html
pub fn min_width(mut self, min_width: u32) -> Self {
self.min_width = min_width;
self
}
/// Sets the padding of the [`Button`].
///
/// [`Button`]: struct.Button.html
pub fn padding(mut self, padding: u16) -> Self {
self.padding = padding;
self
}
/// Sets the [`Background`] of the [`Button`].
///
/// [`Button`]: struct.Button.html
/// [`Background`]: ../../struct.Background.html
pub fn background(mut self, background: Background) -> Self {
self.background = Some(background);
self
}
/// Sets the border radius of the [`Button`].
///
/// [`Button`]: struct.Button.html
pub fn border_radius(mut self, border_radius: u16) -> Self {
self.border_radius = border_radius;
self
@ -103,6 +98,9 @@ impl<'a, Message, Element> Button<'a, Message, Element> {
/// [`Button`]: struct.Button.html
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct State {
/// Whether the [`Button`] is currently being pressed.
///
/// [`Button`]: struct.Button.html
pub is_pressed: bool,
}
@ -113,12 +111,4 @@ impl State {
pub fn new() -> State {
State::default()
}
/// Returns whether the associated [`Button`] is currently being pressed or
/// not.
///
/// [`Button`]: struct.Button.html
pub fn is_pressed(&self) -> bool {
self.is_pressed
}
}

1
core/src/widget/column.rs
View File

@ -7,6 +7,7 @@ use std::u32;
/// A [`Column`] will try to fill the horizontal space of its container.
///
/// [`Column`]: struct.Column.html
#[allow(missing_docs)]
pub struct Column<Element> {
pub spacing: u16,
pub padding: u16,

4
core/src/widget/container.rs
View File

@ -2,7 +2,11 @@ use crate::{Align, Length};
use std::u32;
/// An element decorating some content.
///
/// It is normally used for alignment purposes.
#[derive(Debug)]
#[allow(missing_docs)]
pub struct Container<Element> {
pub width: Length,
pub height: Length,

1
core/src/widget/row.rs
View File

@ -7,6 +7,7 @@ use std::u32;
/// A [`Row`] will try to fill the horizontal space of its container.
///
/// [`Row`]: struct.Row.html
#[allow(missing_docs)]
pub struct Row<Element> {
pub spacing: u16,
pub padding: u16,

35
core/src/widget/scrollable.rs
View File

@ -1,7 +1,11 @@
//! Navigate an endless amount of content with a scrollbar.
use crate::{Align, Column, Length, Point, Rectangle};
use std::u32;
/// A widget that can vertically display an infinite amount of content with a
/// scrollbar.
#[allow(missing_docs)]
#[derive(Debug)]
pub struct Scrollable<'a, Element> {
pub state: &'a mut State,
@ -11,6 +15,10 @@ pub struct Scrollable<'a, Element> {
}
impl<'a, Element> Scrollable<'a, Element> {
/// Creates a new [`Scrollable`] with the given [`State`].
///
/// [`Scrollable`]: struct.Scrollable.html
/// [`State`]: struct.State.html
pub fn new(state: &'a mut State) -> Self {
Scrollable {
state,
@ -90,17 +98,30 @@ impl<'a, Element> Scrollable<'a, Element> {
}
}
/// The local state of a [`Scrollable`].
///
/// [`Scrollable`]: struct.Scrollable.html
#[derive(Debug, Clone, Copy, Default)]
pub struct State {
/// The position where the scrollbar was grabbed at, if it's currently
/// grabbed.
pub scrollbar_grabbed_at: Option<Point>,
offset: u32,
}
impl State {
/// Creates a new [`State`] with the scrollbar located at the top.
///
/// [`State`]: struct.State.html
pub fn new() -> Self {
State::default()
}
/// Apply a scrolling offset to the current [`State`], given the bounds of
/// the [`Scrollable`] and its contents.
///
/// [`Scrollable`]: struct.Scrollable.html
/// [`State`]: struct.State.html
pub fn scroll(
&mut self,
delta_y: f32,
@ -117,6 +138,14 @@ impl State {
as u32;
}
/// Moves the scroll position to a relative amount, given the bounds of
/// the [`Scrollable`] and its contents.
///
/// `0` represents scrollbar at the top, while `1` represents scrollbar at
/// the bottom.
///
/// [`Scrollable`]: struct.Scrollable.html
/// [`State`]: struct.State.html
pub fn scroll_to(
&mut self,
percentage: f32,
@ -127,6 +156,11 @@ impl State {
.max(0.0) as u32;
}
/// Returns the current scrolling offset of the [`State`], given the bounds
/// of the [`Scrollable`] and its contents.
///
/// [`Scrollable`]: struct.Scrollable.html
/// [`State`]: struct.State.html
pub fn offset(&self, bounds: Rectangle, content_bounds: Rectangle) -> u32 {
let hidden_content =
(content_bounds.height - bounds.height).max(0.0).round() as u32;
@ -134,6 +168,7 @@ impl State {
self.offset.min(hidden_content)
}
/// Returns whether the scrollbar is currently grabbed or not.
pub fn is_scrollbar_grabbed(&self) -> bool {
self.scrollbar_grabbed_at.is_some()
}

13
core/src/widget/slider.rs
View File

@ -31,19 +31,12 @@ use std::rc::Rc;
/// ```
///
/// ![Slider drawn by Coffee's renderer](https://github.com/hecrj/coffee/blob/bda9818f823dfcb8a7ad0ff4940b4d4b387b5208/images/ui/slider.png?raw=true)
#[allow(missing_docs)]
pub struct Slider<'a, Message> {
/// The state of the slider
pub state: &'a mut State,
/// The range of the slider
pub range: RangeInclusive<f32>,
/// The current value of the slider
pub value: f32,
/// The function to produce messages on change
pub on_change: Rc<Box<dyn Fn(f32) -> Message>>,
pub width: Length,
}
@ -53,6 +46,7 @@ impl<'a, Message> std::fmt::Debug for Slider<'a, Message> {
.field("state", &self.state)
.field("range", &self.range)
.field("value", &self.value)
.field("width", &self.width)
.finish()
}
}
@ -102,6 +96,9 @@ impl<'a, Message> Slider<'a, Message> {
/// [`Slider`]: struct.Slider.html
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct State {
/// Whether the [`Slider`] is currently being dragged or not.
///
/// [`Slider`]: struct.Slider.html
pub is_dragging: bool,
}

8
core/src/widget/text.rs
View File

@ -12,6 +12,7 @@ use crate::{Color, Font, Length};
/// .size(40);
/// ```
#[derive(Debug, Clone)]
#[allow(missing_docs)]
pub struct Text {
pub content: String,
pub size: Option<u16>,
@ -48,14 +49,19 @@ impl Text {
self
}
/// Sets the `Color` of the [`Text`].
/// Sets the [`Color`] of the [`Text`].
///
/// [`Text`]: struct.Text.html
/// [`Color`]: ../../struct.Color.html
pub fn color<C: Into<Color>>(mut self, color: C) -> Self {
self.color = Some(color.into());
self
}
/// Sets the [`Font`] of the [`Text`].
///
/// [`Text`]: struct.Text.html
/// [`Font`]: ../../struct.Font.html
pub fn font(mut self, font: Font) -> Self {
self.font = font;
self

66
core/src/widget/text_input.rs
View File

@ -1,5 +1,13 @@
//! Display fields that can be filled with text.
//!
//! A [`TextInput`] has some local [`State`].
//!
//! [`TextInput`]: struct.TextInput.html
//! [`State`]: struct.State.html
use crate::Length;
/// A widget that can be filled with text by using a keyboard.
#[allow(missing_docs)]
pub struct TextInput<'a, Message> {
pub state: &'a mut State,
pub placeholder: String,
@ -13,6 +21,9 @@ pub struct TextInput<'a, Message> {
}
impl<'a, Message> TextInput<'a, Message> {
/// Creates a new [`TextInput`].
///
/// [`TextInput`]: struct.TextInput.html
pub fn new<F>(
state: &'a mut State,
placeholder: &str,
@ -59,11 +70,18 @@ impl<'a, Message> TextInput<'a, Message> {
self
}
/// Sets the text size of the [`TextInput`].
///
/// [`TextInput`]: struct.TextInput.html
pub fn size(mut self, size: u16) -> Self {
self.size = Some(size);
self
}
/// Sets the message that should be produced when the [`TextInput`] is
/// focused and the enter key is pressed.
///
/// [`TextInput`]: struct.TextInput.html
pub fn on_submit(mut self, message: Message) -> Self {
self.on_submit = Some(message);
self
@ -80,17 +98,29 @@ where
}
}
/// The state of a [`TextInput`].
///
/// [`TextInput`]: struct.TextInput.html
#[derive(Debug, Default, Clone)]
pub struct State {
/// Whether the [`TextInput`] is focused or not.
///
/// [`TextInput`]: struct.TextInput.html
pub is_focused: bool,
cursor_position: usize,
}
impl State {
/// Creates a new [`State`], representing an unfocused [`TextInput`].
///
/// [`State`]: struct.State.html
pub fn new() -> Self {
Self::default()
}
/// Creates a new [`State`], representing a focused [`TextInput`].
///
/// [`State`]: struct.State.html
pub fn focused() -> Self {
use std::usize;
@ -100,6 +130,9 @@ impl State {
}
}
/// Moves the cursor of a [`TextInput`] to the right.
///
/// [`TextInput`]: struct.TextInput.html
pub fn move_cursor_right(&mut self, value: &Value) {
let current = self.cursor_position(value);
@ -108,6 +141,9 @@ impl State {
}
}
/// Moves the cursor of a [`TextInput`] to the left.
///
/// [`TextInput`]: struct.TextInput.html
pub fn move_cursor_left(&mut self, value: &Value) {
let current = self.cursor_position(value);
@ -116,41 +152,69 @@ impl State {
}
}
/// Moves the cursor of a [`TextInput`] to the end.
///
/// [`TextInput`]: struct.TextInput.html
pub fn move_cursor_to_end(&mut self, value: &Value) {
self.cursor_position = value.len();
}
/// Returns the cursor position of a [`TextInput`].
///
/// [`TextInput`]: struct.TextInput.html
pub fn cursor_position(&self, value: &Value) -> usize {
self.cursor_position.min(value.len())
}
}
/// The value of a [`TextInput`].
///
/// [`TextInput`]: struct.TextInput.html
// TODO: Use `unicode-segmentation`
#[derive(Debug)]
pub struct Value(Vec<char>);
impl Value {
/// Creates a new [`Value`] from a string slice.
///
/// [`Value`]: struct.Value.html
pub fn new(string: &str) -> Self {
Self(string.chars().collect())
}
/// Returns the total amount of `char` in the [`Value`].
///
/// [`Value`]: struct.Value.html
pub fn len(&self) -> usize {
self.0.len()
}
/// Returns a new [`Value`] containing the `char` until the given `index`.
///
/// [`Value`]: struct.Value.html
pub fn until(&self, index: usize) -> Self {
Self(self.0[..index.min(self.len())].to_vec())
}
/// Converts the [`Value`] into a `String`.
///
/// [`Value`]: struct.Value.html
pub fn to_string(&self) -> String {
use std::iter::FromIterator;
String::from_iter(self.0.iter())
}
/// Inserts a new `char` at the given `index`.
///
/// [`Value`]: struct.Value.html
pub fn insert(&mut self, index: usize, c: char) {
self.0.insert(index, c);
}
/// Removes the `char` at the given `index`.
///
/// [`Value`]: struct.Value.html
pub fn remove(&mut self, index: usize) {
self.0.remove(index);
let _ = self.0.remove(index);
}
}

1
rustfmt.toml
View File

@ -1 +1,2 @@
max_width=80
wrap_comments=true