API documentation for awesome, a highly configurable X window manager (version devel).
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 API. |
| awful.keygrabber | A keyboard grabbing and transaction object. |
| client | A process window. |
| drawable | awesome drawable API. |
| gears.timer | Timer objects and functions. |
| mousegrabber | awesome mousegrabber API. |
| naughty.action | A notification action. |
| naughty.notification | A notification object. |
| root | awesome root window API. |
| screen | awesome screen API. |
| tag | awesome tag API. |
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 | awesome mouse API. |
Declarative_rules
| ruled.client | Rules for clients. |
| ruled.notifications | Rules for notifications. |
Widgets
| awful.widget.button | A simple button widget. |
| awful.widget.clienticon | Container showing the icon of a client. |
| awful.widget.keyboardlayout | |
| 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 | Watch widget. |
| 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. |
| naughty.widget.message | A notification content message. |
| naughty.widget.title | A notification title. |
| wibox.widget.calendar | A calendar widget. |
| wibox.widget.checkbox | A boolean display widget. |
| wibox.widget.graph | A graph widget. |
| 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 | |
| wibox.widget.textbox | A widget to display either plain or HTML text. |
| wibox.widget.textclock | Text clock widget. |
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. |
| wibox.container.arcchart | A circular chart (arc chart). |
| 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 | A fixed layout may be initialized with any number of child widgets, and
during runtime widgets may be added and removed dynamically. |
| wibox.layout.flex | A flex layout may be initialized with any number of child widgets, and
during runtime widgets may be added and removed dynamically. |
| wibox.layout.grid | A grid layout. |
| wibox.layout.manual | A layout with widgets added at specific positions. |
| wibox.layout.ratio | A layout filling all the available space. |
| wibox.layout.stack | A stacked layout. |
Popups_and_bars
| awful.hotkeys_popup.widget | Popup widget which shows current hotkeys and their descriptions. |
| awful.menu | A menu for awful. |
| awful.popup | An auto-resized, free floating or modal wibox built around a widget. |
| awful.titlebar | Titlebars for awful. |
| 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 calendar popup wibox. |
| 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. |
| wibox |
Utility_libraries
| gears.debug | |
| gears.filesystem | Filesystem module for gears. |
| gears.geometry | Helper functions used to compute geometries. |
| gears.math | Math module for gears. |
| gears.object | The object oriented programming base class used by various Awesome widgets and components. |
| gears.protected_call | |
| gears.sort | Extra sorting algorithms. |
| gears.string | String module for gears. |
| gears.table | Table module for gears. |
| gears.wallpaper | Functions for setting the wallpaper. |
Theme_related_libraries
| beautiful | Theme library. |
| gears.color | This module simplifies the creation of cairo pattern objects. |
| gears.shape | Module dedicated to gather common shape painters. |
Libraries
| awful.completion | Completion module. |
| awful.hotkeys_popup | Popup widget which shows current hotkeys and their descriptions. |
| awful.layout | Layout module for awful. |
| awful.permissions | Implements EWMH requests handling. |
| awful.placement | Algorithms used to place various drawables. |
| awful.prompt | Prompt module for awful. |
| awful.rules | This module has been moved to ruled.client |
| awful.spawn | Spawning of programs. |
| awful.util | Utility module for awful. |
| dbus | awesome D-Bus API |
| gears.matcher | A module to build a set of properties based on a graph of rules. |
| gears.surface | |
| menubar.menu_gen | Menu generation module for menubar |
| menubar.utils | Utility module for menubar |
| naughty | Notification library. |
| selection | awesome selection (clipboard) API |
| wibox.widget |
Sample files
| rc.lua | The default rc.lua file. |
| theme.lua | The default theme file. |
Classes
| awful.widget.common | |
| 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 |
| signals | Handling of signals. |
| wibox.drawable | Handling of drawables. |
| wibox.hierarchy | Management of widget hierarchies. |
| wibox.widget.base | |
| xproperties | Handling of X properties. |