Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document the theme crate (#18690)

Browse source 
This PR enables required documentation for the `theme` crate starts on
documenting it.

The end goal is to have all meaningful documentation in the crate filled
out – However I'm not sure that just adding `#![deny(missing_docs)]` to
the whole crate is the right approach.

I don't know that having 200+ "The color of the _ color" field docs is
useful however–In the short term I've excluded some of the modules that
contain structs with a ton of fields (`colors, `status`, etc.) until we
decide what the right solution here is.

Next steps are to clean up the crate, removing unused modules or those
with low usage in favor of other approaches.

Changes in this PR:
- Enable the `deny(missing_docs)` lint for the `theme` crate 
- Start documenting a subset of the crate.
- Enable `#![allow(missing_docs)]` for some modules.


Release Notes:

- N/A
This commit is contained in:
Nate Butler 2024-10-03 10:27:19 -04:00 • committed by GitHub
parent dc85378b96
commit 773ad6bfd1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 152 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

70
crates/theme/src/settings.rs
View file

@ -35,6 +35,9 @@ const MIN_LINE_HEIGHT: f32 = 1.0;
Deserialize,
JsonSchema,
)]
/// Specifies the density of the UI.
/// Note: This setting is still experimental. See [this tracking issue](https://github.com/zed-industries/zed/issues/18078)
#[serde(rename_all = "snake_case")]
pub enum UiDensity {
/// A denser UI with tighter spacing and smaller elements.
@ -50,6 +53,8 @@ pub enum UiDensity {
}
impl UiDensity {
/// The spacing ratio of a given density.
/// TODO: Standardize usage throughout the app or remove
pub fn spacing_ratio(self) -> f32 {
match self {
UiDensity::Compact => 0.75,
@ -80,17 +85,43 @@ impl From<UiDensity> for String {
}
}
/// Customizable settings for the UI and theme system.
#[derive(Clone)]
pub struct ThemeSettings {
/// The UI font size. Determines the size of text in the UI,
/// as well as the size of a [gpui::Rems] unit.
///
/// Changing this will impact the size of all UI elements.
pub ui_font_size: Pixels,
/// The font used for UI elements.
pub ui_font: Font,
pub buffer_font: Font,
/// The font size used for buffers, and the terminal.
///
/// The terminal font size can be overridden using it's own setting.
pub buffer_font_size: Pixels,
/// The font used for buffers, and the terminal.
///
/// The terminal font family can be overridden using it's own setting.
pub buffer_font: Font,
/// The line height for buffers, and the terminal.
///
/// Changing this may affect the spacing of some UI elements.
///
/// The terminal font family can be overridden using it's own setting.
pub buffer_line_height: BufferLineHeight,
/// The current theme selection.
/// TODO: Document this further
pub theme_selection: Option<ThemeSelection>,
/// The active theme.
pub active_theme: Arc<Theme>,
/// Manual overrides for the active theme.
///
/// Note: This setting is still experimental. See [this tracking issue](https://github.com/zed-industries/zed/issues/18078)
pub theme_overrides: Option<ThemeStyleContent>,
/// The density of the UI.
/// Note: This setting is still experimental. See [this tracking issue](
pub ui_density: UiDensity,
/// The amount of fading applied to unnecessary code.
pub unnecessary_code_fade: f32,
}
@ -181,15 +212,21 @@ pub(crate) struct AdjustedUiFontSize(Pixels);
impl Global for AdjustedUiFontSize {}
/// Represents the selection of a theme, which can be either static or dynamic.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum ThemeSelection {
/// A static theme selection, represented by a single theme name.
Static(#[schemars(schema_with = "theme_name_ref")] String),
/// A dynamic theme selection, which can change based the [ThemeMode].
Dynamic {
/// The mode used to determine which theme to use.
#[serde(default)]
mode: ThemeMode,
/// The theme to use for light mode.
#[schemars(schema_with = "theme_name_ref")]
light: String,
/// The theme to use for dark mode.
#[schemars(schema_with = "theme_name_ref")]
dark: String,
},
@ -199,6 +236,12 @@ fn theme_name_ref(_: &mut SchemaGenerator) -> Schema {
Schema::new_ref("#/definitions/ThemeName".into())
}
// TODO: Rename ThemeMode -> ThemeAppearanceMode
/// The mode use to select a theme.
///
/// `Light` and `Dark` will select their respective themes.
///
/// `System` will select the theme based on the system's appearance.
#[derive(Debug, PartialEq, Eq, Clone, Copy, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ThemeMode {
@ -214,6 +257,7 @@ pub enum ThemeMode {
}
impl ThemeSelection {
/// Returns the theme name for the selected [ThemeMode].
pub fn theme(&self, system_appearance: Appearance) -> &str {
match self {
Self::Static(theme) => theme,
@ -228,6 +272,7 @@ impl ThemeSelection {
}
}
/// Returns the [ThemeMode] for the [ThemeSelection].
pub fn mode(&self) -> Option<ThemeMode> {
match self {
ThemeSelection::Static(_) => None,
@ -327,6 +372,7 @@ impl ThemeSettingsContent {
}
}
/// Sets the mode for the theme.
pub fn set_mode(&mut self, mode: ThemeMode) {
if let Some(selection) = self.theme.as_mut() {
match selection {
@ -355,16 +401,23 @@ impl ThemeSettingsContent {
}
}
/// The buffer's line height.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, JsonSchema, Default)]
#[serde(rename_all = "snake_case")]
pub enum BufferLineHeight {
/// A less dense line height.
#[default]
Comfortable,
/// The default line height.
Standard,
/// A custom line height.
///
/// A line height of 1.0 is the height of the buffer's font size.
Custom(f32),
}
impl BufferLineHeight {
/// Returns the value of the line height.
pub fn value(&self) -> f32 {
match self {
BufferLineHeight::Comfortable => 1.618,
@ -375,12 +428,15 @@ impl BufferLineHeight {
}
impl ThemeSettings {
/// Returns the [AdjustedBufferFontSize].
pub fn buffer_font_size(&self, cx: &AppContext) -> Pixels {
cx.try_global::<AdjustedBufferFontSize>()
.map_or(self.buffer_font_size, |size| size.0)
.max(MIN_FONT_SIZE)
}
// TODO: Rename: `line_height` -> `buffer_line_height`
/// Returns the buffer's line height.
pub fn line_height(&self) -> f32 {
f32::max(self.buffer_line_height.value(), MIN_LINE_HEIGHT)
}
@ -433,6 +489,7 @@ impl ThemeSettings {
}
}
/// Observe changes to the adjusted buffer font size.
pub fn observe_buffer_font_size_adjustment<V: 'static>(
cx: &mut ViewContext<V>,
f: impl 'static + Fn(&mut V, &mut ViewContext<V>),
@ -440,6 +497,7 @@ pub fn observe_buffer_font_size_adjustment<V: 'static>(
cx.observe_global::<AdjustedBufferFontSize>(f)
}
/// Sets the adjusted buffer font size.
pub fn adjusted_font_size(size: Pixels, cx: &mut AppContext) -> Pixels {
if let Some(AdjustedBufferFontSize(adjusted_size)) = cx.try_global::<AdjustedBufferFontSize>() {
let buffer_font_size = ThemeSettings::get_global(cx).buffer_font_size;
@ -451,12 +509,14 @@ pub fn adjusted_font_size(size: Pixels, cx: &mut AppContext) -> Pixels {
.max(MIN_FONT_SIZE)
}
/// Returns the adjusted buffer font size.
pub fn get_buffer_font_size(cx: &AppContext) -> Pixels {
let buffer_font_size = ThemeSettings::get_global(cx).buffer_font_size;
cx.try_global::<AdjustedBufferFontSize>()
.map_or(buffer_font_size, |adjusted_size| adjusted_size.0)
}
/// Adjusts the buffer font size.
pub fn adjust_buffer_font_size(cx: &mut AppContext, f: fn(&mut Pixels)) {
let buffer_font_size = ThemeSettings::get_global(cx).buffer_font_size;
let mut adjusted_size = cx
@ -469,10 +529,12 @@ pub fn adjust_buffer_font_size(cx: &mut AppContext, f: fn(&mut Pixels)) {
cx.refresh();
}
/// Returns whether the buffer font size has been adjusted.
pub fn has_adjusted_buffer_font_size(cx: &mut AppContext) -> bool {
cx.has_global::<AdjustedBufferFontSize>()
}
/// Resets the buffer font size to the default value.
pub fn reset_buffer_font_size(cx: &mut AppContext) {
if cx.has_global::<AdjustedBufferFontSize>() {
cx.remove_global::<AdjustedBufferFontSize>();
@ -480,6 +542,8 @@ pub fn reset_buffer_font_size(cx: &mut AppContext) {
}
}
// TODO: Make private, change usages to use `get_ui_font_size` instead.
#[allow(missing_docs)]
pub fn setup_ui_font(cx: &mut WindowContext) -> gpui::Font {
let (ui_font, ui_font_size) = {
let theme_settings = ThemeSettings::get_global(cx);
@ -491,12 +555,14 @@ pub fn setup_ui_font(cx: &mut WindowContext) -> gpui::Font {
ui_font
}
/// Gets the adjusted UI font size.
pub fn get_ui_font_size(cx: &AppContext) -> Pixels {
let ui_font_size = ThemeSettings::get_global(cx).ui_font_size;
cx.try_global::<AdjustedUiFontSize>()
.map_or(ui_font_size, |adjusted_size| adjusted_size.0)
}
/// Sets the adjusted UI font size.
pub fn adjust_ui_font_size(cx: &mut AppContext, f: fn(&mut Pixels)) {
let ui_font_size = ThemeSettings::get_global(cx).ui_font_size;
let mut adjusted_size = cx
@ -509,10 +575,12 @@ pub fn adjust_ui_font_size(cx: &mut AppContext, f: fn(&mut Pixels)) {
cx.refresh();
}
/// Returns whether the UI font size has been adjusted.
pub fn has_adjusted_ui_font_size(cx: &mut AppContext) -> bool {
cx.has_global::<AdjustedUiFontSize>()
}
/// Resets the UI font size to the default value.
pub fn reset_ui_font_size(cx: &mut AppContext) {
if cx.has_global::<AdjustedUiFontSize>() {
cx.remove_global::<AdjustedUiFontSize>();