diff --git a/src/style.rs b/src/style.rs index 6bbc9e2..0f0a069 100644 --- a/src/style.rs +++ b/src/style.rs @@ -1,3 +1,5 @@ +//! `style` contains the primitives used to control how your user interface will look. + use bitflags::bitflags; #[derive(Debug, Clone, Copy, PartialEq)] @@ -25,6 +27,17 @@ pub enum Color { } bitflags! { + /// Modifier changes the way a piece of text is displayed. + /// + /// They are bitflags so they can easily be composed. + /// + /// ## Examples + /// + /// ```rust + /// # use tui::style::Modifier; + /// + /// let m = Modifier::BOLD | Modifier::ITALIC; + /// ``` #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct Modifier: u16 { const BOLD = 0b0000_0000_0001; @@ -39,11 +52,32 @@ bitflags! { } } +/// Style let you control the main characteristics of the displayed elements. +/// +/// ## Examples +/// +/// ```rust +/// # use tui::style::{Color, Modifier, Style}; +/// // Using the raw struct initialization: +/// let s = Style { +/// fg: Color::Black, +/// bg: Color::Green, +/// modifier: Modifier::ITALIC | Modifier::BOLD +/// }; +/// // Using the provided builder pattern: +/// let s = Style::default() +/// .fg(Color::Black) +/// .bg(Color::Green) +/// .modifier(Modifier::ITALIC | Modifier::BOLD); +/// ``` #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct Style { + /// The foreground color. pub fg: Color, + /// The background color. pub bg: Color, + /// The emphasis applied to the text graphemes. pub modifier: Modifier, } @@ -61,20 +95,63 @@ impl Style { modifier: Modifier::empty(), } } + + /// Reinitializes the style properties. Both colors are put back to `Color::Reset` while + /// all modifiers are cleared. + /// + /// ## Examples + /// + /// ```rust + /// # use tui::style::{Color, Modifier, Style}; + /// let mut s = Style::default().fg(Color::Red).bg(Color::Green).modifier(Modifier::BOLD); + /// s.reset(); + /// assert_eq!(s.fg, Color::Reset); + /// assert_eq!(s.bg, Color::Reset); + /// assert_eq!(s.modifier, Modifier::empty()); + /// ``` pub fn reset(&mut self) { self.fg = Color::Reset; self.bg = Color::Reset; self.modifier = Modifier::empty(); } + /// Changes the foreground color. + /// + /// ## Examples + /// + /// ```rust + /// # use tui::style::{Color, Style}; + /// let s = Style::default().fg(Color::Red); + /// assert_eq!(s.fg, Color::Red); + /// ``` pub const fn fg(mut self, color: Color) -> Style { self.fg = color; self } + + /// Changes the background color. + /// + /// ## Examples + /// + /// ```rust + /// # use tui::style::{Color, Style}; + /// let s = Style::default().bg(Color::Red); + /// assert_eq!(s.bg, Color::Red); + /// ``` pub const fn bg(mut self, color: Color) -> Style { self.bg = color; self } + + /// Changes the emphasis. + /// + /// ## Examples + /// + /// ```rust + /// # use tui::style::{Modifier, Style}; + /// let s = Style::default().modifier(Modifier::BOLD | Modifier::ITALIC); + /// assert_eq!(s.modifier, Modifier::BOLD | Modifier::ITALIC); + /// ``` pub const fn modifier(mut self, modifier: Modifier) -> Style { self.modifier = modifier; self