Module: beautiful

Key+value based theme library and associated utility modules.

Info:

Static module functions

beautiful.gtk.get_theme_variables () -> table Get GTK+3 theme variables from GtkStyleContext
beautiful.get_font (name) -> lgi.Pango.FontDescription Get a font description.
beautiful.get_merged_font (name, merge) -> lgi.Pango.FontDescription Get a new font with merged attributes, based on another one.
beautiful.get_font_height (name) -> number Get the height of a font.
beautiful.init (config) -> true or nil Function that initializes the theme settings.
beautiful.get () -> table 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) -> table Recolor titlebar icons.
beautiful.theme_assets.recolor_layout (theme, color) -> table Recolor layout icons.
beautiful.xresources.get_current_theme () -> table 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) -> integer Compute resulting size applying current DPI value (optionally per screen).

Theme variables

beautiful.font string The default font.
beautiful.bg_normal color The default background color.
beautiful.bg_focus color The default focused element background color.
beautiful.bg_urgent color The default urgent element background color.
beautiful.bg_minimize color The default minimized element background color.
beautiful.fg_normal color The default focused element foreground (text) color.
beautiful.fg_focus color The default focused element foreground (text) color.
beautiful.fg_urgent color The default urgent element foreground (text) color.
beautiful.fg_minimize color The default minimized element foreground (text) color.
beautiful.wallpaper string or gears.surface The wallpaper path.
beautiful.icon_theme string The icon theme name.
beautiful.awesome_icon string or gears.surface The Awesome icon path.

Deprecated functions

beautiful.recolor_titlebar_normal (theme, color) Recolor unfocused titlebar icons. Deprecated
beautiful.recolor_titlebar_focus (theme, color) Recolor focused titlebar icons. Deprecated
beautiful.xresources.get_dpi (s) Get global or per-screen DPI value falling back to xrdb. Deprecated

Fields

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


Static module functions

🔗 beautiful.gtk.get_theme_variables () -> table
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) -> lgi.Pango.FontDescription
Get a font description.

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

Parameters:

Name Type(s) Description
name string or lgi.Pango.FontDescription The name of the font.

Returns:

    lgi.Pango.FontDescription
🔗 beautiful.get_merged_font (name, merge) -> lgi.Pango.FontDescription
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 Type(s) Description
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) -> number
Get the height of a font.

Parameters:

Name Type(s) Description
name string Name of the font.

Returns:

    number The font height.
🔗 beautiful.init (config) -> true or nil

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 = {}
    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:

Name Type(s) Description
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 () -> table
Get the current theme.

Returns:

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

Parameters:

Name Type(s) Description
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:

Name Type(s) Description
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:

Name Type(s) Description
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:

Name Type(s) Description
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:

Name Type(s) Description
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:

Name Type(s) Description
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) -> table
Recolor titlebar icons.

Parameters:

Name Type(s) Description
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) -> table
Recolor layout icons.

Parameters:

Name Type(s) Description
theme table Beautiful theme table
color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
🔗 beautiful.xresources.get_current_theme () -> table
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:

Name Type(s) Description
dpi number DPI value.
s Optional integer Screen.
🔗 beautiful.xresources.apply_dpi (size, s) -> integer
Compute resulting size applying current DPI value (optionally per screen).

Parameters:

Name Type(s) Description
size number Size
s Optional integer or screen The screen.

Returns:

    integer Resulting size (rounded to integer).

Theme variables

🔗 beautiful.font string
The default font.
Click to display more

Used by:
🔗 beautiful.bg_normal color
The default background color.

The background color can be transparent. If there is a compositing manager such as compton, then it will be real transparency and may include blur (provided by the compositor). When there is no compositor, it will take a picture of the wallpaper and blend it.

Click to display more

Used by:

  • awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • bg The background of the wibox.
  • bg The background of the wibox.
  • bg The background of the wibox.
🔗 beautiful.bg_focus color
The default focused element background color.
Click to display more

Used by:
🔗 beautiful.bg_urgent color
The default urgent element background color.
Click to display more

Used by:
🔗 beautiful.bg_minimize color
The default minimized element background color.
Click to display more

Used by:
🔗 beautiful.fg_normal color
The default focused element foreground (text) color.
Click to display more

Used by:

  • awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.
  • border_color The border color.
  • border_color The border color.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • awful.widget.prompt Create a prompt widget which will launch a command.
  • border_color Border color.
  • border_color Border color.
  • fg The foreground (text) of the wibox.
  • fg The foreground (text) of the wibox.
  • fg The foreground (text) of the wibox.
  • border_color Set the color for the border.
  • shape_border_color When a `shape` is set, also draw a border.
🔗 beautiful.fg_focus color
The default focused element foreground (text) color.
Click to display more

Used by:
🔗 beautiful.fg_urgent color
The default urgent element foreground (text) color.
Click to display more

Used by:
🔗 beautiful.fg_minimize color
The default minimized element foreground (text) color.
Click to display more

Used by:
🔗 beautiful.wallpaper string or gears.surface
The wallpaper path.
Click to display more

Used by:

  • rc.lua The default rc.lua file.
🔗 beautiful.icon_theme string
The icon theme name. It has to be a directory in /usr/share/icons or an XDG icon folder.
Click to display more

Used by:
🔗 beautiful.awesome_icon string or gears.surface
The Awesome icon path.
Click to display more

Used by:

  • rc.lua The default rc.lua file.

Deprecated functions

🔗 beautiful.recolor_titlebar_normal (theme, color)
Recolor unfocused titlebar icons. This method is deprecated. Use a beautiful.theme_assets.recolor_titlebar.

Parameters:

Name Type(s) Description
theme table Beautiful theme table
color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
🔗 beautiful.recolor_titlebar_focus (theme, color)
Recolor focused titlebar icons. This method is deprecated. Use a beautiful.theme_assets.recolor_titlebar.

Parameters:

Name Type(s) Description
theme table Beautiful theme table
color color Icons' color.

Returns:

    table Beautiful theme table with the images recolored.
🔗 beautiful.xresources.get_dpi (s)
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:

Name Type(s) Description
s Optional integer or screen The screen.

Returns:

    number DPI value.

Fields

🔗 beautiful.theme_path string
The current theme path (if any)
generated by LDoc 1.5.0