Module: beautiful

Theme library.

Info:

Static module functions

beautiful.gtk.get_theme_variables () Get GTK+3 theme variables from GtkStyleContext
beautiful.get_font (name) Get a font description.
beautiful.get_merged_font (name, merge) Get a new font with merged attributes, based on another one.
beautiful.get_font_height (name) Get the height of a font.
beautiful.init (config) Function that initializes the theme settings.
beautiful.get () Get the current theme.
beautiful.theme_assets.taglist_squares_sel (size, fg) Generate selected taglist square.
beautiful.theme_assets.taglist_squares_unsel (size, fg) Generate unselected taglist square.
beautiful.theme_assets.gen_awesome_name (cr, height, bg, fg, alt_fg) Put Awesome WM name onto cairo surface.
beautiful.theme_assets.gen_logo (cr, width, height, bg, fg) Put Awesome WM logo onto cairo surface.
beautiful.theme_assets.awesome_icon (size, bg, fg) Generate Awesome WM logo.
beautiful.theme_assets.wallpaper (bg, fg, alt_fg, s) Generate Awesome WM wallpaper.
beautiful.theme_assets.recolor_titlebar (theme, color, state, postfix, toggle_state) Recolor titlebar icons.
beautiful.theme_assets.recolor_layout (theme, color) Recolor layout icons.
beautiful.xresources.get_current_theme () Get current base colorscheme from xrdb.
beautiful.xresources.set_dpi (dpi[, s]) Set DPI for a given screen (defaults to global).
beautiful.xresources.apply_dpi (size[, s]) Compute resulting size applying current DPI value (optionally per screen).

Theme variables

font string The default font.
useless_gap number The gap between clients.
border_width number The client border width.
border_normal color The default clients border color.
border_focus color The focused client border color.
border_marked color The marked clients border color.
wallpaper string or gears.surface The wallpaper path.
awesome_icon string or gears.surface The Awesome icon path.

Deprecated functions

beautiful.recolor_titlebar_normal [deprecated] Recolor unfocused titlebar icons.
beautiful.recolor_titlebar_focus [deprecated] Recolor focused titlebar icons.
beautiful.xresources.get_dpi [deprecated] Get global or per-screen DPI value falling back to xrdb.

Fields

beautiful.theme_path string The current theme path (if any)


Static module functions

beautiful.gtk.get_theme_variables ()
Get GTK+3 theme variables from GtkStyleContext

Returns:

    table Key-value table with the following structure:
    Result key StyleContext key StyleContext fallback #1 StyleContext fallback #2 GTK Widget fallback
    font_size Label font-size
    font_family Label font-family
    bg_color theme_bg_color Window bg
    fg_color theme_fg_color Window fg
    base_color theme_base_color Entry bg
    text_color theme_text_color Entry fg
    button_bg_color theme_button_bg_color theme_bg_color Button bg
    button_fg_color theme_button_fg_color theme_fg_color Button fg
    button_border_color Button border-color
    button_border_radius Button border-radius
    button_border_width Button border-top-width
    selected_bg_color theme_selected_bg_color ToggleButton bg
    selected_fg_color theme_selected_fg_color ToggleButton fg
    menubar_bg_color menubar_bg_color theme_bg_color HeaderBar bg
    menubar_fg_color menubar_fg_color theme_fg_color HeaderBar fg
    header_button_bg_color header_button_bg_color menubar_bg_color theme_bg_color HeaderBar > Button bg
    header_button_fg_color header_button_fg_color menubar_fg_color theme_fg_color HeaderBar > Button fg
    header_button_border_color HeaderBar > Button border-color
    error_color error_color error_bg_color destructive Button bg
    error_bg_color error_bg_color error_color destructive Button bg
    error_fg_color error_fg_color theme_selected_fg_color destructive Button fg
    warning_color warning_color warning_bg_color
    warning_bg_color warning_bg_color warning_color
    warning_fg_color warning_fg_color theme_selected_fg_color
    success_color success_color success_bg_color
    success_bg_color success_bg_color success_color
    success_fg_color success_fg_color theme_selected_fg_color
    tooltip_bg_color theme_tooltip_bg_color theme_bg_color
    tooltip_fg_color theme_tooltip_fg_color theme_fg_color
    osd_bg_color osd_bg theme_tooltip_bg_color theme_bg_color
    osd_fg_color osd_fg theme_tooltip_fg_color theme_fg_color
    osd_border_color osd_borders_color osd_fg_color
    wm_bg_color wm_bg menubar_bg_color theme_bg_color HeaderBar bg
    wm_border_focused_color wm_border_focused theme_selected_bg_color ToggleButton bg
    wm_border_unfocused_color wm_border_unfocused wm_border menubar_bg_colorHeaderBar bg
    wm_title_focused_color wm_title_focused wm_title theme_selected_fg_color ToggleButton fg
    wm_title_unfocused_color wm_title_unfocused wm_unfocused_title menubar_fg_colorHeaderBar fg
    wm_icons_focused_color wm_icons_focused wm_title_focused theme_selected_fg_color ToggleButton fg
    wm_icons_unfocused_color wm_icons_unfocused wm_title_unfocused menubar_fg_color HeaderBar fg
beautiful.get_font (name)
Get a font description.

See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription.

Parameters:

  • name string or lgi.Pango.FontDescription The name of the font.

Returns:

    lgi.Pango.FontDescription
beautiful.get_merged_font (name, merge)
Get a new font with merged attributes, based on another one.

See https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string.

Parameters:

  • name string or Pango.FontDescription The base font.
  • merge string Attributes that should be merged, e.g. “bold”.

Returns:

    lgi.Pango.FontDescription
beautiful.get_font_height (name)
Get the height of a font.

Parameters:

  • name Name of the font.
beautiful.init (config)

Function that initializes the theme settings. Should be run at the beginning of the awesome configuration file (normally rc.lua).

Example usages:

-- Using a table
beautiful.init({font = 'Monospace Bold 10'})

-- From a config file
beautiful.init("<path>/theme.lua")

Example “/theme.lua” (see 05-awesomerc.md:Variable_definitions):

theme = setmetatable({}, { __index = function() error("May not access theme before beautiful.init()") end })
    theme.font = 'Monospace Bold 10'
return theme

Example using the return value:

local beautiful = require("beautiful")
if not beautiful.init("<path>/theme.lua") then
    beautiful.init("<path>/.last.theme.lua") -- a known good fallback
end

Parameters:

  • config string or table The theme to load. It can be either the path to the theme file (which should return a table) or directly a table containing all the theme values.

Returns:

    true or nil True if successful, nil in case of error.
beautiful.get ()
Get the current theme.

Returns:

    table The current theme table.
beautiful.theme_assets.taglist_squares_sel (size, fg)
Generate selected taglist square.

Parameters:

  • size number Size.
  • fg color Background color.

Returns:

    Image with the square.
beautiful.theme_assets.taglist_squares_unsel (size, fg)
Generate unselected taglist square.

Parameters:

  • size number Size.
  • fg color Background color.

Returns:

    Image with the square.
beautiful.theme_assets.gen_awesome_name (cr, height, bg, fg, alt_fg)
Put Awesome WM name onto cairo surface.

Parameters:

  • cr Cairo surface.
  • height number Height.
  • bg color Background color.
  • fg color Main foreground color.
  • alt_fg color Accent foreground color.
beautiful.theme_assets.gen_logo (cr, width, height, bg, fg)
Put Awesome WM logo onto cairo surface.

Parameters:

  • cr Cairo surface.
  • width number Width.
  • height number Height.
  • bg color Background color.
  • fg color Foreground color.
beautiful.theme_assets.awesome_icon (size, bg, fg)
Generate Awesome WM logo.

Parameters:

  • size number Size.
  • bg color Background color.
  • fg color Background color.

Returns:

    Image with the logo.
beautiful.theme_assets.wallpaper (bg, fg, alt_fg, s)
Generate Awesome WM wallpaper.

Parameters:

  • bg color Background color.
  • fg color Main foreground color.
  • alt_fg color Accent foreground color.
  • s screen Screen (to get wallpaper size).

Returns:

    Wallpaper image.
beautiful.theme_assets.recolor_titlebar (theme, color, state, postfix, toggle_state)
Recolor titlebar icons.

Parameters:

  • theme table Beautiful theme table.
  • color color Icons' color.
  • state string "normal" or "focus".
  • postfix string nil, "hover" or "press".
  • toggle_state string nil, "active" or "inactive".

Returns:

    table Beautiful theme table with the images recolored.
beautiful.theme_assets.recolor_layout (theme, color)
Recolor layout icons.

Parameters:

  • theme table Beautiful theme table
  • color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
beautiful.xresources.get_current_theme ()
Get current base colorscheme from xrdb.

Returns:

    table Color table with keys ‘background’, ‘foreground’ and ‘color0’..‘color15’.
beautiful.xresources.set_dpi (dpi[, s])
Set DPI for a given screen (defaults to global).

Parameters:

  • dpi number DPI value.
  • s integer Screen. (optional)
beautiful.xresources.apply_dpi (size[, s])
Compute resulting size applying current DPI value (optionally per screen).

Parameters:

  • size number Size
  • s integer or screen The screen. (optional)

Returns:

    integer Resulting size (rounded to integer).

Theme variables

font (string)
The default font.
useless_gap (number)
The gap between clients.
border_width (number)
The client border width.
border_normal (color)
The default clients border color. Note that only solid colors are supported.
border_focus (color)
The focused client border color. Note that only solid colors are supported.
border_marked (color)
The marked clients border color. Note that only solid colors are supported.
wallpaper (string or gears.surface)
The wallpaper path.
awesome_icon (string or gears.surface)
The Awesome icon path.

Deprecated functions

beautiful.recolor_titlebar_normal [deprecated]
Recolor unfocused titlebar icons. This method is deprecated. Use a beautiful.theme_assets.recolor_titlebar.

Parameters:

  • theme table Beautiful theme table
  • color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
beautiful.recolor_titlebar_focus [deprecated]
Recolor focused titlebar icons. This method is deprecated. Use a beautiful.theme_assets.recolor_titlebar.

Parameters:

  • theme table Beautiful theme table
  • color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
beautiful.xresources.get_dpi [deprecated]
Get global or per-screen DPI value falling back to xrdb.

This function is deprecated. Use s.dpi and avoid getting the DPI without a screen.

Parameters:

  • s integer or screen The screen. (optional)

Returns:

    number DPI value.

Fields

beautiful.theme_path (string)
The current theme path (if any)
generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00