Detailed changes
@@ -37,8 +37,8 @@ impl RenderOnce for FacePile {
}
impl ParentElement for FacePile {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.faces
+ fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
+ self.faces.extend(elements);
}
}
@@ -26,8 +26,8 @@ impl CollabNotification {
}
impl ParentElement for CollabNotification {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -40,14 +40,25 @@ use std::any::{Any, TypeId};
/// register_action!(Paste);
/// ```
pub trait Action: 'static {
+ /// Clone the action into a new box
fn boxed_clone(&self) -> Box<dyn Action>;
+
+ /// Cast the action to the any type
fn as_any(&self) -> &dyn Any;
+
+ /// Do a partial equality check on this action and the other
fn partial_eq(&self, action: &dyn Action) -> bool;
+
+ /// Get the name of this action, for displaying in UI
fn name(&self) -> &str;
+ /// Get the name of this action for debugging
fn debug_name() -> &'static str
where
Self: Sized;
+
+ /// Build this action from a JSON value. This is used to construct actions from the keymap.
+ /// A value of `{}` will be passed for actions that don't have any parameters.
fn build(value: serde_json::Value) -> Result<Box<dyn Action>>
where
Self: Sized;
@@ -62,6 +73,7 @@ impl std::fmt::Debug for dyn Action {
}
impl dyn Action {
+ /// Get the type id of this action
pub fn type_id(&self) -> TypeId {
self.as_any().type_id()
}
@@ -170,6 +182,7 @@ impl ActionRegistry {
macro_rules! actions {
($namespace:path, [ $($name:ident),* $(,)? ]) => {
$(
+ /// The `$name` action see [`gpui::actions!`]
#[derive(::std::cmp::PartialEq, ::std::clone::Clone, ::std::default::Default, ::std::fmt::Debug, gpui::private::serde_derive::Deserialize)]
#[serde(crate = "gpui::private::serde")]
pub struct $name;
@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
mod async_context;
mod entity_map;
mod model_context;
@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
use crate::{
Action, AnyElement, AnyView, AnyWindowHandle, AppCell, AppContext, AsyncAppContext,
AvailableSpace, BackgroundExecutor, Bounds, ClipboardItem, Context, Entity, EventEmitter,
@@ -8,8 +8,12 @@ use std::{
sync::atomic::{AtomicUsize, Ordering::SeqCst},
};
+/// A source of assets for this app to use.
pub trait AssetSource: 'static + Send + Sync {
+ /// Load the given asset from the source path.
fn load(&self, path: &str) -> Result<Cow<[u8]>>;
+
+ /// List the assets at the given path.
fn list(&self, path: &str) -> Result<Vec<SharedString>>;
}
@@ -26,15 +30,19 @@ impl AssetSource for () {
}
}
+/// A unique identifier for the image cache
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct ImageId(usize);
+/// A cached and processed image.
pub struct ImageData {
+ /// The ID associated with this image
pub id: ImageId,
data: ImageBuffer<Bgra<u8>, Vec<u8>>,
}
impl ImageData {
+ /// Create a new image from the given data.
pub fn new(data: ImageBuffer<Bgra<u8>, Vec<u8>>) -> Self {
static NEXT_ID: AtomicUsize = AtomicUsize::new(0);
@@ -44,10 +52,12 @@ impl ImageData {
}
}
+ /// Convert this image into a byte slice.
pub fn as_bytes(&self) -> &[u8] {
&self.data
}
+ /// Get the size of this image, in pixels
pub fn size(&self) -> Size<DevicePixels> {
let (width, height) = self.data.dimensions();
size(width.into(), height.into())
@@ -2,6 +2,7 @@ use anyhow::bail;
use serde::de::{self, Deserialize, Deserializer, Visitor};
use std::fmt;
+/// Convert an RGB hex color code number to a color type
pub fn rgb<C: From<Rgba>>(hex: u32) -> C {
let r = ((hex >> 16) & 0xFF) as f32 / 255.0;
let g = ((hex >> 8) & 0xFF) as f32 / 255.0;
@@ -9,6 +10,7 @@ pub fn rgb<C: From<Rgba>>(hex: u32) -> C {
Rgba { r, g, b, a: 1.0 }.into()
}
+/// Convert an RGBA hex color code number to [`Rgba`]
pub fn rgba(hex: u32) -> Rgba {
let r = ((hex >> 24) & 0xFF) as f32 / 255.0;
let g = ((hex >> 16) & 0xFF) as f32 / 255.0;
@@ -17,11 +19,16 @@ pub fn rgba(hex: u32) -> Rgba {
Rgba { r, g, b, a }
}
+/// An RGBA color
#[derive(PartialEq, Clone, Copy, Default)]
pub struct Rgba {
+ /// The red component of the color, in the range 0.0 to 1.0
pub r: f32,
+ /// The green component of the color, in the range 0.0 to 1.0
pub g: f32,
+ /// The blue component of the color, in the range 0.0 to 1.0
pub b: f32,
+ /// The alpha component of the color, in the range 0.0 to 1.0
pub a: f32,
}
@@ -32,6 +39,8 @@ impl fmt::Debug for Rgba {
}
impl Rgba {
+ /// Create a new [`Rgba`] color by blending this and another color together
+ /// TODO: find the source for this algorithm
pub fn blend(&self, other: Rgba) -> Self {
if other.a >= 1.0 {
other
@@ -165,12 +174,20 @@ impl TryFrom<&'_ str> for Rgba {
}
}
+/// An HSLA color
#[derive(Default, Copy, Clone, Debug)]
#[repr(C)]
pub struct Hsla {
+ /// Hue, in a range from 0 to 1
pub h: f32,
+
+ /// Saturation, in a range from 0 to 1
pub s: f32,
+
+ /// Lightness, in a range from 0 to 1
pub l: f32,
+
+ /// Alpha, in a range from 0 to 1
pub a: f32,
}
@@ -203,38 +220,9 @@ impl Ord for Hsla {
}
}
-impl Hsla {
- pub fn to_rgb(self) -> Rgba {
- self.into()
- }
-
- pub fn red() -> Self {
- red()
- }
-
- pub fn green() -> Self {
- green()
- }
-
- pub fn blue() -> Self {
- blue()
- }
-
- pub fn black() -> Self {
- black()
- }
-
- pub fn white() -> Self {
- white()
- }
-
- pub fn transparent_black() -> Self {
- transparent_black()
- }
-}
-
impl Eq for Hsla {}
+/// Construct an [`Hsla`] object from plain values
pub fn hsla(h: f32, s: f32, l: f32, a: f32) -> Hsla {
Hsla {
h: h.clamp(0., 1.),
@@ -244,6 +232,7 @@ pub fn hsla(h: f32, s: f32, l: f32, a: f32) -> Hsla {
}
}
+/// Pure black in [`Hsla`]
pub fn black() -> Hsla {
Hsla {
h: 0.,
@@ -253,6 +242,7 @@ pub fn black() -> Hsla {
}
}
+/// Transparent black in [`Hsla`]
pub fn transparent_black() -> Hsla {
Hsla {
h: 0.,
@@ -262,6 +252,7 @@ pub fn transparent_black() -> Hsla {
}
}
+/// Pure white in [`Hsla`]
pub fn white() -> Hsla {
Hsla {
h: 0.,
@@ -271,6 +262,7 @@ pub fn white() -> Hsla {
}
}
+/// The color red in [`Hsla`]
pub fn red() -> Hsla {
Hsla {
h: 0.,
@@ -280,6 +272,7 @@ pub fn red() -> Hsla {
}
}
+/// The color blue in [`Hsla`]
pub fn blue() -> Hsla {
Hsla {
h: 0.6,
@@ -289,6 +282,7 @@ pub fn blue() -> Hsla {
}
}
+/// The color green in [`Hsla`]
pub fn green() -> Hsla {
Hsla {
h: 0.33,
@@ -298,6 +292,7 @@ pub fn green() -> Hsla {
}
}
+/// The color yellow in [`Hsla`]
pub fn yellow() -> Hsla {
Hsla {
h: 0.16,
@@ -308,6 +303,41 @@ pub fn yellow() -> Hsla {
}
impl Hsla {
+ /// Converts this HSLA color to an RGBA color.
+ pub fn to_rgb(self) -> Rgba {
+ self.into()
+ }
+
+ /// The color red
+ pub fn red() -> Self {
+ red()
+ }
+
+ /// The color green
+ pub fn green() -> Self {
+ green()
+ }
+
+ /// The color blue
+ pub fn blue() -> Self {
+ blue()
+ }
+
+ /// The color black
+ pub fn black() -> Self {
+ black()
+ }
+
+ /// The color white
+ pub fn white() -> Self {
+ white()
+ }
+
+ /// The color transparent black
+ pub fn transparent_black() -> Self {
+ transparent_black()
+ }
+
/// Returns true if the HSLA color is fully transparent, false otherwise.
pub fn is_transparent(&self) -> bool {
self.a == 0.0
@@ -339,6 +369,7 @@ impl Hsla {
}
}
+ /// Returns a new HSLA color with the same hue, and lightness, but with no saturation.
pub fn grayscale(&self) -> Self {
Hsla {
h: self.h,
@@ -1,3 +1,39 @@
+//! Elements are the workhorses of GPUI. They are responsible for laying out and painting all of
+//! the contents of a window. Elements form a tree and are laid out according to the web layout
+//! standards as implemented by [taffy](https://github.com/DioxusLabs/taffy). Most of the time,
+//! you won't need to interact with this module or these APIs directly. Elements provide their
+//! own APIs and GPUI, or other element implementation, uses the APIs in this module to convert
+//! that element tree into the pixels you see on the screen.
+//!
+//! # Element Basics
+//!
+//! Elements are constructed by calling [`Render::render()`] on the root view of the window, which
+//! which recursively constructs the element tree from the current state of the application.
+//! These elements are then laid out by Taffy, and painted to the screen according to their own
+//! implementation of [`Element::paint()`]. Before the start of the next frame, the entire element
+//! tree and any callbacks they have registered with GPUI are dropped and the process repeats.
+//!
+//! But some state is too simple and voluminous to store in every view that needs it, e.g.
+//! whether a hover has been started or not. For this, GPUI provides the [`Element::State`], type.
+//! If an element returns an [`ElementId`] from [`IntoElement::element_id()`], and that element id
+//! appears in the same place relative to other views and ElementIds in the frame, then the previous
+//! frame's state will be passed to the element's layout and paint methods.
+//!
+//! # Implementing your own elements
+//!
+//! Elements are intended to be the low level, imperative API to GPUI. They are responsible for upholding,
+//! or breaking, GPUI's features as they deem nescessary. As an example, most GPUI elements are expected
+//! to stay in the bounds that their parent element gives them. But with [`WindowContext::break_content_mask`],
+//! you can ignore this restriction and paint anywhere inside of the window's bounds. This is useful for overlays
+//! and popups and anything else that shows up 'on top' of other elements.
+//! With great power, comes great responsibility.
+//!
+//! However, most of the time, you won't need to implement your own elements. GPUI provides a number of
+//! elements that should cover most common use cases out of the box and it's recommended that you use those.
+//! to construct `components`, using the `RenderOnce` trait and the `#[derive(IntoElement)]` macro. Only implement
+//! components when you need to take manual control of the layout and painting process, such as when using
+//! your own custom layout algorithm or rendering a code editor.
+
use crate::{
util::FluentBuilder, ArenaBox, AvailableSpace, BorrowWindow, Bounds, ElementId, LayoutId,
Pixels, Point, Size, ViewContext, WindowContext, ELEMENT_ARENA,
@@ -7,20 +43,27 @@ pub(crate) use smallvec::SmallVec;
use std::{any::Any, fmt::Debug};
/// Implemented by types that participate in laying out and painting the contents of a window.
-/// Elements form a tree and are laid out according to web-based layout rules.
-/// Rather than calling methods on implementers of this trait directly, you'll usually call `into_any` to convert them into an AnyElement, which manages state internally.
-/// You can create custom elements by implementing this trait.
+/// Elements form a tree and are laid out according to web-based layout rules, as implemented by Taffy.
+/// You can create custom elements by implementing this trait, see the module-level documentation
+/// for more details.
pub trait Element: 'static + IntoElement {
+ /// The type of state to store for this element between frames. See the module-level documentation
+ /// for details.
type State: 'static;
+ /// Before an element can be painted, we need to know where it's going to be and how big it is.
+ /// Use this method to request a layout from Taffy and initialize the element's state.
fn request_layout(
&mut self,
state: Option<Self::State>,
cx: &mut WindowContext,
) -> (LayoutId, Self::State);
+ /// Once layout has been completed, this method will be called to paint the element to the screen.
+ /// The state argument is the same state that was returned from [`Element::request_layout()`].
fn paint(&mut self, bounds: Bounds<Pixels>, state: &mut Self::State, cx: &mut WindowContext);
+ /// Convert this element into a dynamically-typed [`AnyElement`].
fn into_any(self) -> AnyElement {
AnyElement::new(self)
}
@@ -29,6 +72,7 @@ pub trait Element: 'static + IntoElement {
/// Implemented by any type that can be converted into an element.
pub trait IntoElement: Sized {
/// The specific type of element into which the implementing type is converted.
+ /// Useful for converting other types into elements automatically, like Strings
type Element: Element;
/// The [`ElementId`] of self once converted into an [`Element`].
@@ -81,7 +125,10 @@ pub trait IntoElement: Sized {
impl<T: IntoElement> FluentBuilder for T {}
+/// An object that can be drawn to the screen. This is the trait that distinguishes `Views` from
+/// models. Views are drawn to the screen and care about the current window's state, models are not and do not.
pub trait Render: 'static + Sized {
+ /// Render this view into an element tree.
fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement;
}
@@ -92,35 +139,49 @@ impl Render for () {
}
/// You can derive [`IntoElement`] on any type that implements this trait.
-/// It is used to allow views to be expressed in terms of abstract data.
+/// It is used to construct reusable `components` out of plain data. Think of
+/// components as a recipe for a certain pattern of elements. RenderOnce allows
+/// you to invoke this pattern, without breaking the fluent builder pattern of
+/// the element APIs.
pub trait RenderOnce: 'static {
+ /// Render this component into an element tree. Note that this method
+ /// takes ownership of self, as compared to [`Render::render()`] method
+ /// which takes a mutable reference.
fn render(self, cx: &mut WindowContext) -> impl IntoElement;
}
+/// This is a helper trait to provide a uniform interface for constructing elements that
+/// can accept any number of any kind of child elements
pub trait ParentElement {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]>;
+ /// Extend this element's children with the given child elements.
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>);
+ /// Add a single child element to this element.
fn child(mut self, child: impl IntoElement) -> Self
where
Self: Sized,
{
- self.children_mut().push(child.into_element().into_any());
+ self.extend(std::iter::once(child.into_element().into_any()));
self
}
+ /// Add multiple child elements to this element.
fn children(mut self, children: impl IntoIterator<Item = impl IntoElement>) -> Self
where
Self: Sized,
{
- self.children_mut()
- .extend(children.into_iter().map(|child| child.into_any_element()));
+ self.extend(children.into_iter().map(|child| child.into_any_element()));
self
}
}
+/// An element for rendering components. An implementation detail of the [`IntoElement`] derive macro
+/// for [`RenderOnce`]
+#[doc(hidden)]
pub struct Component<C: RenderOnce>(Option<C>);
impl<C: RenderOnce> Component<C> {
+ /// Create a new component from the given RenderOnce type.
pub fn new(component: C) -> Self {
Component(Some(component))
}
@@ -156,8 +217,9 @@ impl<C: RenderOnce> IntoElement for Component<C> {
}
}
+/// A globally unique identifier for an element, used to track state across frames.
#[derive(Deref, DerefMut, Default, Clone, Debug, Eq, PartialEq, Hash)]
-pub struct GlobalElementId(SmallVec<[ElementId; 32]>);
+pub(crate) struct GlobalElementId(SmallVec<[ElementId; 32]>);
trait ElementObject {
fn element_id(&self) -> Option<ElementId>;
@@ -180,7 +242,8 @@ trait ElementObject {
);
}
-pub struct DrawableElement<E: Element> {
+/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
+pub(crate) struct DrawableElement<E: Element> {
element: Option<E>,
phase: ElementDrawPhase<E::State>,
}
@@ -363,10 +426,11 @@ where
}
}
+/// A dynamically typed element that can be used to store any element type.
pub struct AnyElement(ArenaBox<dyn ElementObject>);
impl AnyElement {
- pub fn new<E>(element: E) -> Self
+ pub(crate) fn new<E>(element: E) -> Self
where
E: 'static + Element,
E::State: Any,
@@ -377,10 +441,13 @@ impl AnyElement {
AnyElement(element)
}
+ /// Request the layout ID of the element stored in this `AnyElement`.
+ /// Used for laying out child elements in a parent element.
pub fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId {
self.0.request_layout(cx)
}
+ /// Paints the element stored in this `AnyElement`.
pub fn paint(&mut self, cx: &mut WindowContext) {
self.0.paint(cx)
}
@@ -404,6 +471,7 @@ impl AnyElement {
self.0.draw(origin, available_space, cx)
}
+ /// Returns the element ID of the element stored in this `AnyElement`, if any.
pub fn inner_id(&self) -> Option<ElementId> {
self.0.element_id()
}
@@ -771,8 +771,8 @@ impl InteractiveElement for Div {
}
impl ParentElement for Div {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -1824,8 +1824,8 @@ impl<E> ParentElement for Focusable<E>
where
E: ParentElement,
{
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- self.element.children_mut()
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.element.extend(elements)
}
}
@@ -1898,8 +1898,8 @@ impl<E> ParentElement for Stateful<E>
where
E: ParentElement,
{
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- self.element.children_mut()
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.element.extend(elements)
}
}
@@ -60,8 +60,8 @@ impl Overlay {
}
impl ParentElement for Overlay {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -1,3 +1,5 @@
+#![deny(missing_docs)]
+
#[macro_use]
mod action;
mod app;
@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
mod app_menu;
mod keystroke;
#[cfg(target_os = "macos")]
@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
use crate::{
seal::Sealed, AnyElement, AnyModel, AnyWeakModel, AppContext, AvailableSpace, BorrowWindow,
Bounds, ContentMask, Element, ElementId, Entity, EntityId, Flatten, FocusHandle, FocusableView,
@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
use crate::{
px, size, transparent_black, Action, AnyDrag, AnyTooltip, AnyView, AppContext, Arena,
AsyncWindowContext, AvailableSpace, Bounds, BoxShadow, Context, Corners, CursorStyle,
@@ -67,8 +67,8 @@ impl StoryContainer {
}
impl ParentElement for StoryContainer {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -372,7 +372,7 @@ impl RenderOnce for StorySection {
}
impl ParentElement for StorySection {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -407,8 +407,8 @@ impl VisibleOnHover for ButtonLike {
}
impl ParentElement for ButtonLike {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -78,8 +78,8 @@ impl LabelCommon for LabelLike {
}
impl ParentElement for LabelLike {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -40,8 +40,8 @@ impl List {
}
impl ParentElement for List {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -141,8 +141,8 @@ impl Selectable for ListItem {
}
impl ParentElement for ListItem {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -74,7 +74,7 @@ impl Popover {
}
impl ParentElement for Popover {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -92,8 +92,8 @@ impl Selectable for Tab {
}
impl ParentElement for Tab {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -83,8 +83,8 @@ impl TabBar {
}
impl ParentElement for TabBar {
- fn children_mut(&mut self) -> &mut SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}
@@ -904,8 +904,8 @@ mod element {
}
impl ParentElement for PaneAxisElement {
- fn children_mut(&mut self) -> &mut smallvec::SmallVec<[AnyElement; 2]> {
- &mut self.children
+ fn extend(&mut self, elements: impl Iterator<Item = AnyElement>) {
+ self.children.extend(elements)
}
}