diff --git a/lua/wezterm/types/config.lua b/lua/wezterm/types/config.lua index 0dbbcff..2f073f0 100644 --- a/lua/wezterm/types/config.lua +++ b/lua/wezterm/types/config.lua @@ -269,8 +269,6 @@ local horiz_align = { --- ---@field width? "Cover"|"Contain"|number|string ----@alias AllFontAttributes Fonts|FontAttributes|FontFamilyAttributes - ---@enum (key) FontRules.Blink local blink = { None = 1, @@ -280,7 +278,7 @@ local blink = { ---@class FontRules ---@field blink? FontRules.Blink ----@field font? AllFontAttributes +---@field font? TextStyle ---@field intensity? FormatItemAttribute.Intensity ---@field invisible? boolean ---@field italic? boolean @@ -613,7 +611,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- - [`wezterm.font()`](lua://Wezterm.font) --- ----@field char_select_font? Fonts|FontFamilyAttributes +---@field char_select_font? TextStyle ---Specifies the size of the font used with [`CharSelect`](https://wezterm.org/config/lua/keyassignment/CharSelect.html). --- ---@field char_select_font_size? number @@ -713,7 +711,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font()`](lua://Wezterm.font) --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- ----@field command_palette_font? AllFontAttributes +---@field command_palette_font? TextStyle ---Specifies the size of the font used with `ActivateCommandPalette`. --- ---See: @@ -1108,7 +1106,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font()`](lua://Wezterm.font) --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- ----@field font? AllFontAttributes +---@field font? TextStyle ---@field font_colr_rasterizer? FontRasterizer ---By default, wezterm will use an appropriate system-specific method ---for locating the fonts that you specify using the options below. @@ -1818,7 +1816,7 @@ local exit_behavior_messaging = { ---config.pane_select_font = wezterm.font 'Roboto' ---``` --- ----@field pane_select_font? AllFontAttributes +---@field pane_select_font? TextStyle ---@field pane_select_font_size? number ---If non-zero, specifies the period (in seconds) at which various statistics are logged. --- diff --git a/lua/wezterm/types/wezterm.lua b/lua/wezterm/types/wezterm.lua index a1b7ccc..62906fa 100644 --- a/lua/wezterm/types/wezterm.lua +++ b/lua/wezterm/types/wezterm.lua @@ -456,6 +456,13 @@ local font_stretch = { UltraExpanded = 1, } +---@enum (key) FontStyle +local font_style = { + Italic = 1, + Normal = 1, + Oblique = 1, +} + ---@enum (key) FreeTypeLoadFlags local freetype_load_flags = { DEFAUlT = 1, @@ -466,18 +473,6 @@ local freetype_load_flags = { NO_HINTING = 1, } ----@class FontAttributes ----@field is_fallback? boolean ----@field is_synthetic? boolean ----@field scale? number ----@field stretch? FontStretch ----Whether the font should be an italic variant. ---- ----@field style? "Normal"|"Italic"|"Oblique" ----Whether the font should be a bold variant. ---- ----@field weight? FontWeight - ---@enum (key) FreeTypeTarget local freetype_target = { HorizontalLcd = 1, @@ -487,10 +482,10 @@ local freetype_target = { VerticalLcd = 1, } ----`FontAttributes`-like class but with font family ----and other extensions included. +---@class FontAttributesBase +---To control whether a font is considered to have emoji (rather than text) +---presentation glyphs for emoji. --- ----@class FontFamilyAttributes: FontAttributes ---@field assume_emoji_presentation? boolean ---@field family string ---you can combine the flags like `"NO_HINTING|MONOCHROME"` @@ -511,9 +506,47 @@ local freetype_target = { --- - [`config.font_shaper`](lua://Config.font_shaper) --- ---@field harfbuzz_features? HarfbuzzFeatures[] +---@field scale? number +---@field stretch? FontStretch +---This option will only be respected if the `italic` option is `nil`. +--- +---@field style? FontStyle +---@field weight? FontWeight + +---Argument type for `Wezterm.font()` and `Wezterm.font_with_fallback()`. +---@class FontFamilyAttributes: FontAttributesBase +---Setting this option to `true`, will overwrite the `style` option to `Italic`. +---Setting this option to `false` will overwrite the `style` option to `Normal`. +--- +---@field italic? boolean + +---Corresponds to the internal `FontAttributes` struct that is used to +---select a single named font. +--- +---@class FontAttributes: FontAttributesBase +---@field is_fallback? boolean +---@field is_synthetic? boolean + +---@class TextStyleAttributes +---@field bold? boolean +---If set, when rendering text that is set to the default +---foreground color, use this color instead. This is most +---useful in a `Config.font_rules` section to implement changing +---the text color for eg: bold text. +--- +---For more information and examples, see: +--- - [Font Rules](ttps://wezterm.org/config/lua/config/font_rules.html) +--- - [`config.font_rules`](lua://Config.font_rules) +--- +---@field foreground? string +---@field italic? boolean +---@field stretch? FontStretch +---@field style? FontStyle +---@field weight? FontWeight ----@class Fonts +---@class TextStyle ---@field fonts FontAttributes[] +---@field foreground? string ---@class WindowFrameConfig ---@field active_titlebar_bg? string @@ -531,7 +564,7 @@ local freetype_target = { ---@field button_fg? string ---@field button_hover_bg? string ---@field button_hover_fg? string ----@field font? AllFontAttributes +---@field font? TextStyle ---@field font_size? number ---@field inactive_titlebar_bg? string ---@field inactive_titlebar_border_bottom? string @@ -1221,7 +1254,7 @@ function M.emit(event, ...) end function M.enumerate_ssh_hosts(ssh_config_file_name) end ---This function constructs a Lua table that corresponds to the internal ----`FontFamilyAttributes` struct that is used to select a single named font: +---`FontAttributes` struct that is used to select a single named font: --- ---```lua ---local wezterm = require 'wezterm' @@ -1242,24 +1275,32 @@ function M.enumerate_ssh_hosts(ssh_config_file_name) end --- - The postscript name, which is an ostensibly unique name identifying a given font and style --- that is encoded into the font by the font designer. --- ----See also: ---- - [`FontAttributes`](lua://FontAttributes) ---- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +---When specifying a font using its family name, the second `attributes` parameter is +---an **optional** table that can be used to specify style attributes. +--- +---See: +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) --- ----@param name string ----@param attributes? FontAttributes ----@return Fonts|FontFamilyAttributes -function M.font(name, attributes) end +---@param font string|FontFamilyAttributes +---@param attributes? TextStyleAttributes +---@return TextStyle +function M.font(font, attributes) end ---This function constructs a Lua table that corresponds to the internal ----`FontFamilyAttributes` struct that is used to select a single named font. +---`FontAttributes` struct that is used to select a single named font. --- ----When specifying a font using its family name, the second attributes parameter is ----an **optional** table that can be used to specify style attributes. +---The first parameter is a table where the font family and the attributes are combined. --- ----You can use the expanded form mentioned above to override freetype and harfbuzz settings +---You can use this expanded table form to override freetype and harfbuzz settings ---just for the specified font. --- +---The second attributes parameter is an **optional** table that can also be used +---to specify style attributes. +--- +---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over +---any attributes specified in the first `font` parameter. +--- ---This example shows how to disable the default ligature feature just for this particular font: --- ---```lua @@ -1272,30 +1313,54 @@ function M.font(name, attributes) end ---} ---``` --- ----The following options can be specified in the same way: ---- - [`harfbuzz_features`](lua://FontFamilyAttributes.harfbuzz_features) ---- - [`freetype_load_target`](lua://FontFamilyAttributes.freetype_load_target) ---- - [`freetype_render_target`](lua://FontFamilyAttributes.freetype_render_target) ---- - [`freetype_load_flags`](lua://FontFamilyAttributes.freetype_load_flags) ---- - [`assume_emoji_presentation`](lua://FontFamilyAttributes.assume_emoji_presentation) ---- to control whether a font is considered to have emoji (rather than text) presentation glyphs ---- for emoji ---- ---- See: ---- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +---See: +--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) --- ----@param attributes FontFamilyAttributes ----@return Fonts|FontFamilyAttributes fonts -function M.font(attributes) end +---@param font FontFamilyAttributes +---@param attributes? TextStyleAttributes +---@return TextStyle +function M.font(font, attributes) end ----TODO: Complete description. +---This function constructs a lua table that configures a font with fallback processing. +---Glyphs are looked up in the first font in the list but if missing the next font is checked and so on. --- ----Here's some [info](https://wezterm.org/config/lua/wezterm/font_with_fallback.html) on this ----function. +---The first parameter is a table listing the fonts in their preferred order. +---The fonts can be specified by the their family or using the alternative form where the family and attributes +---are specified as part of the same lua table: +--- +---```lua +---local wezterm = require 'wezterm' +---return { +--- font = wezterm.font_with_fallback { +--- { +--- family = 'JetBrains Mono' +--- harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }, +--- weight = 'Medium' +--- }, +--- { family = 'Terminus', weight = 'Bold' }, +--- 'Noto Color Emoji', +---} +---``` +--- +---WezTerm implicitly adds its default fallback to the list that you specify. +--- +---The second `attributes` parameter is an **optional** table that can also be used +---to specify style attributes. +--- +---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over +---any attributes specified in the individual font tables and will affect all listed fonts. +--- +---See: +--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) --- ----@param fonts (string|FontAttributes)[] ----@return Fonts fallback_fonts -function M.font_with_fallback(fonts) end +---@param fonts (string|FontFamilyAttributes)[] +---@param attributes? TextStyleAttributes +---@return TextStyle +function M.font_with_fallback(fonts, attributes) end ---Can be used to produce a formatted string with terminal graphic attributes ---such as `bold`, `italic` and `colors`.