API documentation for awesome, a highly configurable X window manager (version master-gb54e50a).
Welcome to the documentation for the Awesome window manager. Below you find an overview of the individual parts which links to the full documentation.
If you are a new user, you may want to read 07-my-first-awesome.md to get started. In 05-awesomerc.md, the default configuration is explained.
If you already used awesome in the past, 89-NEWS.md and 17-porting-tips.md should be useful for you.
Default configuration components name:
Guides
Major libraries
AwesomeWM ship multiple libraries. Here is an overview of the purpose and scope of those libraries.
| Library | Description |
|---|---|
gears | Utilities such as color parsing and objects |
| wibox | Awesome own generic widget framework |
awful | Everything related to window managment |
awful.widget | Window management related widgets |
| awful.layout | The default stateless client tiling module. |
ruled | Define declarative rules on various events |
| naughty | Notifications |
| menubar | XDG (application) menu implementation |
| beautiful | Awesome theme module |
Core_components
| awesome | AwesomeWM lifecycle and low-level APIs. |
| awful.keygrabber | A keyboard grabbing and transaction object. |
| client | A process window managed by AwesomeWM. |
| drawable | Low-level API to allow Cairo to draw on clients and wiboxes. |
| gears.timer | Class to execute code at specific intervals. |
| mousegrabber | Set a callback to process all mouse events. |
| naughty.action | A notification action. |
| naughty.notification | Notification manipulation class. |
| root | APIs to interact with the root window. |
| screen | A physical or virtual screen object. |
| tag | Labelled container where client objects can be stored. |
Input_handling
| awful.button | Create easily new buttons objects ignoring certain modifiers. |
| awful.key | Create easily new key objects ignoring certain modifiers. |
| awful.keyboard | Utilities related to the keyboard and keybindings. |
| mouse | Manipulate and inspect the mouse cursor. |
Declarative_rules
| ruled.client | Apply properties to a new client based on pre-determined rules. |
| ruled.notifications | Apply properties to a new naughty.notification based on pre-determined rules. |
Widgets
| awful.widget.button | A simple button widget based on a background image. |
| awful.widget.clienticon | Container showing the icon of a client. |
| awful.widget.keyboardlayout | Display the current keyboard layout name in a widget. |
| awful.widget.launcher | A button widget which hosts a menu or starts a command. |
| awful.widget.layoutbox | Display the current client layout (awful.layout) icon or name. |
| awful.widget.layoutlist | Display the available client layouts for a screen. |
| awful.widget.prompt | The widget version of awful.prompt. |
| awful.widget.taglist | Taglist widget module for awful. |
| awful.widget.tasklist | Tasklist widget module for awful. |
| awful.widget.watch | Execute a command at a set interval and display its output. |
| naughty.list.actions | Manage a notification action list. |
| naughty.list.notifications | Get a list of all currently active notifications. |
| naughty.widget.icon | A notification square icon widget. |
| naughty.widget.message | A notification content message widget. |
| naughty.widget.title | A notification title widget. |
| wibox.widget.calendar | Display a monthly or yearly calendar. |
| wibox.widget.checkbox | A boolean display widget. |
| wibox.widget.graph | Display multiple values as a stream of bars. |
| wibox.widget.imagebox | A widget to display an image. |
| wibox.widget.piechart | Display percentage in a circle. |
| wibox.widget.progressbar | A progressbar widget. |
| wibox.widget.separator | A flexible separator widget. |
| wibox.widget.slider | An interactive mouse based slider widget. |
| wibox.widget.systray | Container for the various system tray icons. |
| wibox.widget.textbox | A widget to display either plain or HTML text. |
| wibox.widget.textclock | Display the time (and date) in a text box. |
Widget_containers
| awful.widget.only_on_screen | A container that makes a widget display only on a specified screen. |
| naughty.widget.background | A notification background widget. |
| wibox.container.arcchart | A circular chart (arc chart) container. |
| wibox.container.background | A container capable of changing the background color, foreground color and widget shape. |
| wibox.container.constraint | Restrict a widget size using one of multiple available strategies. |
| wibox.container.margin | Add a margin around a widget. |
| wibox.container.mirror | Reflect a widget along one or both axis. |
| wibox.container.place | A container used to place smaller widgets into larger space. |
| wibox.container.radialprogressbar | A circular progressbar wrapper. |
| wibox.container.rotate | A container rotating the conained widget by 90 degrees. |
| wibox.container.scroll | This container scrolls its inner widget inside of the available space. |
| wibox.container.tile | Replicate the content of the widget over and over. |
Widget_layouts
| wibox.layout.align | The align layout has three slots for child widgets. |
| wibox.layout.fixed | Place many widgets in a column or row, until the available space is used up. |
| wibox.layout.flex | Split the space equally between multiple widgets. |
| wibox.layout.grid | Place multiple widgets in multiple rows and columns. |
| wibox.layout.manual | A layout with widgets added at specific positions. |
| wibox.layout.ratio | A layout filling all the available space. |
| wibox.layout.stack | Place multiple widgets on top of each other. |
Popups_and_bars
| awful.hotkeys_popup.widget | Popup widget which shows current hotkeys and their descriptions. |
| awful.menu | Create context menus, optionally with sub-menus. |
| awful.popup | An auto-resized, free floating or modal wibox built around a widget. |
| awful.titlebar | Create widget area on the edge of a client. |
| awful.tooltip | Tooltip module for awesome objects. |
| awful.wallpaper | Allows to use the wibox widget system to draw the wallpaper. |
| awful.wibar | The main AwesomeWM "bar" module. |
| awful.widget.calendar_popup | A popup wibox containing a wibox.widget.calendar widget. |
| menubar | Menubar module, which aims to provide a freedesktop menu alternative. |
| naughty.layout.box | A notification popup widget. |
| naughty.layout.legacy | A notification popup widget (deprecated implementation). |
| wibox | Box where widget can be displayed. |
Utility_libraries
| gears.debug | Utility functions to make development easier. |
| gears.filesystem | Various filesystem utility functions. |
| gears.geometry | Helper functions used to compute geometries. |
| gears.math | Various math related functions. |
| gears.object | The object oriented programming base class used by various Awesome widgets and components. |
| gears.protected_call | Safely call a function and handle errors using gears.debug. |
| gears.sort | Utilities to sort and arrange data. |
| gears.string | Various string manipulation and introspection fuctions. |
| gears.table | Various functions to worj with tables. |
| gears.wallpaper | Functions for setting the wallpaper. |
Theme_related_libraries
| beautiful | Key+value based theme library and associated utility modules. |
| gears.color | This module simplifies the creation of cairo pattern objects. |
| gears.shape | Module dedicated to gather common shape painters. |
Libraries
| awful.completion | Helper utilities for bash-like completion lists. |
| awful.hotkeys_popup | Popup widget which shows current hotkeys and their descriptions. |
| awful.layout | Deterministically lay the clients in a screen workarea. |
| awful.permissions | Default implementation of the various requests handers. |
| awful.placement | Algorithms used to place various drawables. |
| awful.prompt | Convert a wibox.widget.textbox into an input prompt. |
| awful.rules | This module has been moved to ruled.client |
| awful.spawn | Spawn sub-processes and optionally get their output. |
| awful.util | Various small utility functions not worth putting into new modules. |
| dbus | A deprecated low-level D-Bus API DO NOT USE. |
| gears.matcher | A module to build a set of properties based on a graph of rules. |
| gears.surface | Utilities to integrate and manipulate Cairo drawing surfaces. |
| menubar.menu_gen | Menu generation module for menubar |
| menubar.utils | Utility functions for the menubar module. |
| naughty | Notification library. |
| selection | awesome selection (clipboard) API |
| wibox.widget | Utility function for working with widgets. |
Sample files
| rc.lua | The default rc.lua file. |
| theme.lua | The default theme file. |
Classes
| awful.screenshot | Take screenshots of clients, screens, geometry and export to files or widgets. |
| awful.widget.common | This module contains helper functions to manage a layout widgets. |
| gears.cache | Cache object with data that can be garbage-collected. |
| gears.matrix | An implementation of matrices for describing and working with affine transformations. |
| menubar.icon_theme | (Deprecated) class module for icon lookup for menubar |
| menubar.index_theme | (Deprecated) class module for parsing an index.theme file |
| wibox.hierarchy | Management of widget hierarchies. |
| wibox.widget.base | Base class of every widgets, containers and layouts, |
| xproperties | Handling of X properties. |