API documentation for awesome, a highly configurable X window manager (version master-gad0290b).

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:


Major libraries

AwesomeWM ship multiple libraries. Here is an overview of the purpose and scope of those libraries.

Library Description
gearsUtilities such as color parsing and objects
wiboxAwesome own generic widget framework
awfulEverything related to window managment
awful.widgetWindow management related widgets
awful.layoutThe default stateless client tiling module.
ruledDefine declarative rules on various events
menubarXDG (application) menu implementation
beautifulAwesome theme module


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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


generated by LDoc 1.5.0