@@ -7,7 +7,7 @@ use crate::{
SizeRefinement, Styled, TextRun,
};
use collections::HashSet;
-use refineable::{Cascade, Refineable};
+use refineable::Refineable;
use smallvec::SmallVec;
pub use taffy::style::{
AlignContent, AlignItems, AlignSelf, Display, FlexDirection, FlexWrap, JustifyContent,
@@ -15,10 +15,12 @@ pub use taffy::style::{
};
#[cfg(debug_assertions)]
+/// Use this struct for interfacing with the 'debug_below' styling from your own elements.
+/// If a parent element has this style set on it, then this struct will be set as a global in
+/// GPUI.
pub struct DebugBelow;
-pub type StyleCascade = Cascade<Style>;
-
+/// The CSS styling that can be applied to an element via the `Styled` trait
#[derive(Clone, Refineable, Debug)]
#[refineable(Debug)]
pub struct Style {
@@ -104,16 +106,20 @@ pub struct Style {
/// Box Shadow of the element
pub box_shadow: SmallVec<[BoxShadow; 2]>,
- /// TEXT
+ /// The text style of this element
pub text: TextStyleRefinement,
/// The mouse cursor style shown when the mouse pointer is over an element.
pub mouse_cursor: Option<CursorStyle>,
+ /// The z-index to set for this element
pub z_index: Option<u16>,
+ /// Whether to draw a red debugging outline around this element
#[cfg(debug_assertions)]
pub debug: bool,
+
+ /// Whether to draw a red debugging outline around this element and all of it's conforming children
#[cfg(debug_assertions)]
pub debug_below: bool,
}
@@ -124,40 +130,71 @@ impl Styled for StyleRefinement {
}
}
+/// The value of the visibility property, similar to the CSS property `visibility`
#[derive(Default, Clone, Copy, Debug, Eq, PartialEq)]
pub enum Visibility {
+ /// The element should be drawn as normal.
#[default]
Visible,
+ /// The element should not be drawn, but should still take up space in the layout.
Hidden,
}
+/// The possible values of the box-shadow property
#[derive(Clone, Debug)]
pub struct BoxShadow {
+ /// What color should the shadow have?
pub color: Hsla,
+ /// How should it be offset from it's element?
pub offset: Point<Pixels>,
+ /// How much should the shadow be blurred?
pub blur_radius: Pixels,
+ /// How much should the shadow spread?
pub spread_radius: Pixels,
}
+/// How to handle whitespace in text
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub enum WhiteSpace {
+ /// Normal line wrapping when text overflows the width of the element
#[default]
Normal,
+ /// No line wrapping, text will overflow the width of the element
Nowrap,
}
+/// The properties that can be used to style text in GPUI
#[derive(Refineable, Clone, Debug, PartialEq)]
#[refineable(Debug)]
pub struct TextStyle {
+ /// The color of the text
pub color: Hsla,
+
+ /// The font family to use
pub font_family: SharedString,
+
+ /// The font features to use
pub font_features: FontFeatures,
+
+ /// The font size to use, in pixels or rems.
pub font_size: AbsoluteLength,
+
+ /// The line height to use, in pixels or fractions
pub line_height: DefiniteLength,
+
+ /// The font weight, e.g. bold
pub font_weight: FontWeight,
+
+ /// The font style, e.g. italic
pub font_style: FontStyle,
+
+ /// The background color of the text
pub background_color: Option<Hsla>,
+
+ /// The underline style of the text
pub underline: Option<UnderlineStyle>,
+
+ /// How to handle whitespace in the text
pub white_space: WhiteSpace,
}
@@ -180,6 +217,7 @@ impl Default for TextStyle {
}
impl TextStyle {
+ /// Create a new text style with the given highlighting applied.
pub fn highlight(mut self, style: impl Into<HighlightStyle>) -> Self {
let style = style.into();
if let Some(weight) = style.font_weight {
@@ -208,6 +246,7 @@ impl TextStyle {
self
}
+ /// Get the font configured for this text style.
pub fn font(&self) -> Font {
Font {
family: self.font_family.clone(),
@@ -222,6 +261,7 @@ impl TextStyle {
self.line_height.to_pixels(self.font_size, rem_size).round()
}
+ /// Convert this text style into a [`TextRun`], for the given length of the text.
pub fn to_run(&self, len: usize) -> TextRun {
TextRun {
len,
@@ -238,19 +278,33 @@ impl TextStyle {
}
}
+/// A highlight style to apply, similar to a `TextStyle` except
+/// for a single font, uniformly sized and spaced text.
#[derive(Copy, Clone, Debug, Default, PartialEq)]
pub struct HighlightStyle {
+ /// The color of the text
pub color: Option<Hsla>,
+
+ /// The font weight, e.g. bold
pub font_weight: Option<FontWeight>,
+
+ /// The font style, e.g. italic
pub font_style: Option<FontStyle>,
+
+ /// The background color of the text
pub background_color: Option<Hsla>,
+
+ /// The underline style of the text
pub underline: Option<UnderlineStyle>,
+
+ /// Similar to the CSS `opacity` property, this will cause the text to be less vibrant.
pub fade_out: Option<f32>,
}
impl Eq for HighlightStyle {}
impl Style {
+ /// Get the text style in this element style.
pub fn text_style(&self) -> Option<&TextStyleRefinement> {
if self.text.is_some() {
Some(&self.text)
@@ -259,6 +313,8 @@ impl Style {
}
}
+ /// Get the content mask for this element style, based on the given bounds.
+ /// If the element does not hide it's overflow, this will return `None`.
pub fn overflow_mask(
&self,
bounds: Bounds<Pixels>,
@@ -480,20 +536,29 @@ impl Default for Style {
}
}
+/// The properties that can be applied to an underline.
#[derive(Refineable, Copy, Clone, Default, Debug, PartialEq, Eq)]
#[refineable(Debug)]
pub struct UnderlineStyle {
+ /// The thickness of the underline.
pub thickness: Pixels,
+
+ /// The color of the underline.
pub color: Option<Hsla>,
+
+ /// Whether the underline should be wavy, like in a spell checker.
pub wavy: bool,
}
+/// The kinds of fill that can be applied to a shape.
#[derive(Clone, Debug)]
pub enum Fill {
+ /// A solid color fill.
Color(Hsla),
}
impl Fill {
+ /// Unwrap this fill into a solid color, if it is one.
pub fn color(&self) -> Option<Hsla> {
match self {
Fill::Color(color) => Some(*color),
@@ -539,6 +604,8 @@ impl From<&TextStyle> for HighlightStyle {
}
impl HighlightStyle {
+ /// Blend this highlight style with another.
+ /// Non-continuous properties, like font_weight and font_style, are overwritten.
pub fn highlight(&mut self, other: HighlightStyle) {
match (self.color, other.color) {
(Some(self_color), Some(other_color)) => {
@@ -612,6 +679,7 @@ impl From<Rgba> for HighlightStyle {
}
}
+/// Combine and merge the highlights and ranges in the two iterators.
pub fn combine_highlights(
a: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>,
b: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>,
@@ -7,17 +7,21 @@ use crate::{BoxShadow, TextStyleRefinement};
use smallvec::{smallvec, SmallVec};
use taffy::style::{Display, Overflow};
+/// A trait for elements that can be styled.
+/// Use this to opt-in to a CSS-like styling API.
pub trait Styled: Sized {
+ /// Returns a reference to the style memory of this element.
fn style(&mut self) -> &mut StyleRefinement;
gpui_macros::style_helpers!();
+ /// Set the z-index of this element.
fn z_index(mut self, z_index: u16) -> Self {
self.style().z_index = Some(z_index);
self
}
- /// Sets the size of the element to the full width and height.
+ /// Sets the size of the element to sthe full width and height.
fn full(mut self) -> Self {
self.style().size.width = Some(relative(1.).into());
self.style().size.height = Some(relative(1.).into());
@@ -88,6 +92,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the cursor style when hovering over this element
fn cursor(mut self, cursor: CursorStyle) -> Self {
self.style().mouse_cursor = Some(cursor);
self
@@ -511,16 +516,19 @@ pub trait Styled: Sized {
self
}
+ /// Get the text style that has been configured on this element.
fn text_style(&mut self) -> &mut Option<TextStyleRefinement> {
let style: &mut StyleRefinement = self.style();
&mut style.text
}
+ /// Set the text color of this element, this value cascades to it's child elements.
fn text_color(mut self, color: impl Into<Hsla>) -> Self {
self.text_style().get_or_insert_with(Default::default).color = Some(color.into());
self
}
+ /// Set the font weight of this element, this value cascades to it's child elements.
fn font_weight(mut self, weight: FontWeight) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -528,6 +536,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the background color of this element, this value cascades to it's child elements.
fn text_bg(mut self, bg: impl Into<Hsla>) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -535,6 +544,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size of this element, this value cascades to it's child elements.
fn text_size(mut self, size: impl Into<AbsoluteLength>) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -542,6 +552,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'extra small',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_xs(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -549,6 +561,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'small',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_sm(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -556,6 +570,7 @@ pub trait Styled: Sized {
self
}
+ /// Reset the text styling for this element and it's children.
fn text_base(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -563,6 +578,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'large',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_lg(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -570,6 +587,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'extra large',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_xl(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -577,6 +596,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'extra-extra large',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_2xl(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -584,6 +605,8 @@ pub trait Styled: Sized {
self
}
+ /// Set the text size to 'extra-extra-extra large',
+ /// see the [Tailwind Docs](https://tailwindcss.com/docs/font-size#setting-the-font-size)
fn text_3xl(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -591,6 +614,7 @@ pub trait Styled: Sized {
self
}
+ /// Remove the text decoration on this element, this value cascades to it's child elements.
fn text_decoration_none(mut self) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -598,6 +622,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the color for the underline on this element
fn text_decoration_color(mut self, color: impl Into<Hsla>) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -605,6 +630,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to a solid line
fn text_decoration_solid(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -612,6 +638,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to a wavy line
fn text_decoration_wavy(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -619,6 +646,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to be 0 thickness, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
fn text_decoration_0(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -626,6 +654,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to be 1px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
fn text_decoration_1(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -633,6 +662,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to be 2px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
fn text_decoration_2(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -640,6 +670,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to be 4px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
fn text_decoration_4(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -647,6 +678,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the underline to be 8px thick, see the [Tailwind Docs](https://tailwindcss.com/docs/text-decoration-thickness)
fn text_decoration_8(mut self) -> Self {
let style = self.text_style().get_or_insert_with(Default::default);
let underline = style.underline.get_or_insert_with(Default::default);
@@ -654,6 +686,7 @@ pub trait Styled: Sized {
self
}
+ /// Change the font on this element and it's children.
fn font(mut self, family_name: impl Into<SharedString>) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -661,6 +694,7 @@ pub trait Styled: Sized {
self
}
+ /// Set the line height on this element and it's children.
fn line_height(mut self, line_height: impl Into<DefiniteLength>) -> Self {
self.text_style()
.get_or_insert_with(Default::default)
@@ -668,12 +702,14 @@ pub trait Styled: Sized {
self
}
+ /// Draw a debug border around this element.
#[cfg(debug_assertions)]
fn debug(mut self) -> Self {
self.style().debug = Some(true);
self
}
+ /// Draw a debug border on all conforming elements below this element.
#[cfg(debug_assertions)]
fn debug_below(mut self) -> Self {
self.style().debug_below = Some(true);
@@ -4,9 +4,9 @@ use schemars::{
};
macro_rules! create_definitions {
- ($($(#[$meta:meta])* ($name:ident, $idx:expr), ($comment:tt)),* $(,)?) => {
+ ($($(#[$meta:meta])* ($name:ident, $idx:expr)),* $(,)?) => {
- /// The font features that can be configured for a given font.
+ /// The OpenType features that can be configured for a given font.
#[derive(Default, Copy, Clone, Eq, PartialEq, Hash)]
pub struct FontFeatures {
enabled: u64,
@@ -15,7 +15,7 @@ macro_rules! create_definitions {
impl FontFeatures {
$(
- /// $comment
+ /// Get the current value of the corresponding OpenType feature
pub fn $name(&self) -> Option<bool> {
if (self.enabled & (1 << $idx)) != 0 {
Some(true)
@@ -128,7 +128,7 @@ macro_rules! create_definitions {
}
create_definitions!(
- (calt, 0, CALT),
+ (calt, 0),
(case, 1),
(cpsp, 2),
(frac, 3),