Module beautiful - awesome API documentation

# Module `beautiful`

Theme library.

### Info:

- Copyright: 2008-2009 Damien Leone, Julien Danjou
- Author: Damien Leone <damien.leone@gmail.com>,Julien Danjou <julien@danjou.info>

## Functions

get_font (name) | Get a font description.
get_merged_font (name, merge) | Get a new font with merged attributes, based on another one.
get_font_height (name) | Get the height of a font.
init (config) | Function that initializes the theme settings.
get () | Get the current theme.

## Theme variables

font | The default font.
useless_gap | The gap between clients.
border_width | The client border width.
border_normal | The default clients border color.
border_focus | The focused client border color.
border_marked | The marked clients border color.
wallpaper | The wallpaper path.
awesome_icon | The Awesome icon path.

## Fields

theme_path | The current theme path (if any)

## lib.beautiful.theme_assets Functions

theme_assets.taglist_squares_sel (size, fg) | Generate selected taglist square.
theme_assets.taglist_squares_unsel (size, fg) | Generate unselected taglist square.
theme_assets.gen_awesome_name (cr, height, bg, fg, alt_fg) | Put Awesome WM name onto cairo surface.
theme_assets.gen_logo (cr, width, height, bg, fg) | Put Awesome WM logo onto cairo surface.
theme_assets.awesome_icon (size, bg, fg) | Generate Awesome WM logo.
theme_assets.wallpaper (bg, fg, alt_fg, s) | Generate Awesome WM wallpaper.
theme_assets.recolor_titlebar (theme, color, state, postfix) | Recolor titlebar icons.
recolor_titlebar_normal [deprecated] | Recolor unfocused titlebar icons.
recolor_titlebar_focus [deprecated] | Recolor focused titlebar icons.
theme_assets.recolor_layout (theme, color) | Recolor layout icons.

## lib.beautiful.xresources Functions

xresources.get_current_theme () | Get current base colorscheme from xrdb.
xresources.get_dpi [deprecated] | Get global or per-screen DPI value falling back to xrdb.
xresources.set_dpi (dpi[, s]) | Set DPI for a given screen (defaults to global).
xresources.apply_dpi (size[, s]) | Compute resulting size applying current DPI value (optionally per screen).

## Functions

Methods

get_font (name)
  Get a font description.

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

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

  ### Returns:

  lgi.Pango.FontDescription
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.

  - name string or Pango.FontDescription The base font.
  - merge string Attributes that should be merged, e.g. "bold".

  ### Returns:

  lgi.Pango.FontDescription
get_font_height (name)
  Get the height of a font.
  - name Name of the font
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 = {}
          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

  - 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.
get ()
  Get the current theme.

  ### Returns:

  table The current theme table.

## Theme variables

font
  The default font.
useless_gap
  The gap between clients.

  ### Type:

  - number (default 0)
border_width
  The client border width.
border_normal
  The default clients border color. Note that only solid colors are supported.
border_focus
  The focused client border color. Note that only solid colors are supported.
border_marked
  The marked clients border color. Note that only solid colors are supported.
wallpaper
  The wallpaper path.
awesome_icon
  The Awesome icon path.

## Fields

theme_path
  The current theme path (if any)

## lib.beautiful.theme_assets Functions

theme_assets.taglist_squares_sel (size, fg)
  Generate selected taglist square.
  - size number Size.
  - fg color Background color.

  ### Returns:

  Image with the square.
theme_assets.taglist_squares_unsel (size, fg)
  Generate unselected taglist square.
  - size number Size.
  - fg color Background color.

  ### Returns:

  Image with the square.
theme_assets.gen_awesome_name (cr, height, bg, fg, alt_fg)
  Put Awesome WM name onto cairo surface.
  - cr Cairo surface.
  - height number Height.
  - bg color Background color.
  - fg color Main foreground color.
  - alt_fg color Accent foreground color.
theme_assets.gen_logo (cr, width, height, bg, fg)
  Put Awesome WM logo onto cairo surface.
  - cr Cairo surface.
  - width number Width.
  - height number Height.
  - bg color Background color.
  - fg color Foreground color.
theme_assets.awesome_icon (size, bg, fg)
  Generate Awesome WM logo.
  - size number Size.
  - bg color Background color.
  - fg color Background color.

  ### Returns:

  Image with the logo.
theme_assets.wallpaper (bg, fg, alt_fg, s)
  Generate Awesome WM wallpaper.
  - 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.
theme_assets.recolor_titlebar (theme, color, state, postfix)
  Recolor titlebar icons.
  - theme table Beautiful theme table.
  - color color Icons' color.
  - state string `"normal"` or `"focus"`.
  - postfix string `nil`, `"hover"` or `"press"`.

  ### Returns:

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

  ### param:

  - theme table Beautiful theme table
  - color color Icons' color.
recolor_titlebar_focus [deprecated]
  Recolor focused titlebar icons. This method is deprecated. Use a `beautiful.theme_assets.recolor_titlebar`.

  ### param:

  - theme table Beautiful theme table
  - color color Icons' color.
theme_assets.recolor_layout (theme, color)
  Recolor layout icons.
  - theme table Beautiful theme table
  - color color Icons' color.

  ### Returns:

  table Beautiful theme table with the images recolored.

## lib.beautiful.xresources Functions

xresources.get_current_theme ()
  Get current base colorscheme from xrdb.

  ### Returns:

  table Color table with keys 'background', 'foreground' and 'color0'..'color15'
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.

  ### param:

  - s integer or screen The screen. (optional)
xresources.set_dpi (dpi[, s])
  Set DPI for a given screen (defaults to global).
  - dpi number DPI value.
  - s integer Screen. (optional)
xresources.apply_dpi (size[, s])
  Compute resulting size applying current DPI value (optionally per screen).
  - size number Size
  - s integer or screen The screen. (optional)

  ### Returns:

  integer Resulting size (rounded to integer).

generated by LDoc 1.5.0 Last updated 2025-09-27 02:02:16