# Module: `beautiful`

Key+value based theme library and associated utility modules.

### Info:

- Copyright: 2008-2009 Damien Leone, Julien Danjou
- Originally authored by: Damien Leone <damien.leone@gmail.com>,Julien Danjou <julien@danjou.info>
  (Full contributors list available on our github project)

## 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_color` | HeaderBar 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_color` | HeaderBar 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("/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("/theme.lua") then beautiful.init("/.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:

  - `style` A table with values to override each `beautiful.notification_action` values.
  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - font Set a textbox font.
  - font Set a textbox font.
  - font Set a textbox font.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
🔗 beautiful.bg_urgent color
  The default urgent element background color.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
  - `urgent` Set to `true` when the client ask for attention.
🔗 beautiful.bg_minimize color
  The default minimized element background color.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
🔗 beautiful.fg_urgent color
  The default urgent element foreground (text) color.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
  - `urgent` Set to `true` when the client ask for attention.
🔗 beautiful.fg_minimize color
  The default minimized element foreground (text) color.
  Click to display more

  ### Used by:

  - `awful.widget.hotkeys_popup.widget.new` Create an instance of widget with hotkeys help.
  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - menubar.icon_theme.new Class constructor of `icon_theme`
🔗 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