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 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.border | Place widgets or images on the sides, corner and back of another widget. |
| 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 work 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. |