Module: `awesome`

AwesomeWM lifecycle API.

This module contains the functions and signal to manage the lifecycle of the AwesomeWM process. It allows to execute code at specific point from the early initialization all the way to the last events before exiting or restarting.

Additionally it handles signals for spawn and keyboard related events.

Info:

Copyright: 2008-2009 Julien Danjou
Originally authored by: Julien Danjou <julien@danjou.info>
(Full contributors list available on our github project)

Static module functions

awesome.register_xproperty (name, type)	Register a new xproperty.
awesome.quit ([code=0])	Quit awesome.
awesome.exec (cmd)	Execute another application, probably a window manager, to replace awesome.
awesome.restart ()	Restart awesome.
awesome.kill (pid, sig) -> boolean	Send a signal to a process.
awesome.sync ()	Synchronize with the X11 server.
awesome.pixbuf_to_surface (pixbuf, path) -> ()	Translate a GdkPixbuf to a cairo image surface..
awesome.load_image (name) -> () or string	Load an image from a given path.
awesome.set_preferred_icon_size (size)	Set the preferred size for client icons.
awesome.connect_signal (name, func)	Add a global signal.
awesome.disconnect_signal (name, func)	Remove a global signal.
awesome.emit_signal (name, ...)	Emit a global signal.
awesome.spawn (cmd[, use_sn=true[, stdin=false[, stdout=false[, stderr=false[, exit_callback=nil[, cmd=nil]]]]]]) -> (integer, string, integer, integer, integer) or string	Spawn a program.
awesome.xkb_set_layout_group (num)	Switch keyboard layout.
awesome.xkb_get_layout_group () -> integer	Get current layout number.
awesome.xkb_get_group_names () -> string	Get layout short names.

Signals

debug::error	A call into the Lua code aborted with an error.
debug::deprecation	A deprecated Lua function was called.
debug::index::miss	An invalid key was read from an object.
debug::newindex::miss	An invalid key was written to an object.
systray::update	The systray should be updated.
wallpaper_changed	The wallpaper has changed.
xkb::map_changed	Keyboard map has changed.
xkb::group_changed.	Keyboard group has changed.
refresh	Refresh.
startup	AwesomeWM is about to enter the event loop.
exit	AwesomeWM is exiting / about to restart.
screen::change	The output status of a screen has changed.
spawn::canceled	For some reason the application aborted startup
spawn::change	When one of the fields from the spawn::initiated table changes
spawn::completed	An application finished starting
spawn::initiated	When a new client is beginning to start
spawn::timeout	An application started a spawn event but didn't start in time.

Fields

awesome.version	string	The AwesomeWM version.
awesome.release	string	The AwesomeWM release name.
awesome.api_level	string	The AwesomeWM API level.
awesome.conffile	string	The configuration file which has been loaded.
awesome.startup	boolean	True if we are still in startup, false otherwise.
awesome.startup_errors	string	Error message for errors that occurred during startup.
awesome.composite_manager_running	boolean	True if a composite manager is running.
awesome.unix_signal	table	Table mapping between signal numbers and signal identifiers.
awesome.hostname	string	The hostname of the computer on which we are running.
awesome.themes_path	string	The path where themes were installed to.
awesome.icon_path	string	The path where icons were installed to.
awesome.mainloop_timestamp	number	A low-precision timestampt of when the last even loop iteration was started.

Static module functions

awesome.register_xproperty (name, type)

Parameters:

name string The name of the X11 property.
type string One of "string", "number" or "boolean".

awesome.quit ([code=0])

Quit awesome.

Parameters:

code integer The exit code to use when exiting. (default 0)

awesome.exec (cmd)

Execute another application, probably a window manager, to replace awesome.

Parameters:

cmd The command line to execute.

awesome.restart ()

Restart awesome.

awesome.kill (pid, sig) -> boolean

Send a signal to a process.

Parameters:

pid integer Process identifier. 0 and negative values have special meaning. See man 3 kill.
sig integer Signal number. See awesome.unix_signal for a list of signals.

Returns:

boolean

awesome.sync ()

Synchronize with the X11 server. This is needed in the test suite to avoid some race conditions. You should never need to use this function.

awesome.pixbuf_to_surface (pixbuf, path) -> ()

Translate a GdkPixbuf to a cairo image surface..

Parameters:

pixbuf The pixbuf as a light user datum.
path The pixbuf origin path

Returns:

A cairo surface as light user datum.

awesome.load_image (name) -> () or string

Load an image from a given path.

Parameters:

name The file name.

Returns:

A cairo surface as light user datum.

Or

nil
string Error message

awesome.set_preferred_icon_size (size)

Set the preferred size for client icons.

The closest equal or bigger size is picked if present, otherwise the closest smaller size is picked. The default is 0 pixels, ie. the smallest icon.

Parameters:

size The size of the icons in pixels.

awesome.connect_signal (name, func)

Add a global signal.

Parameters:

name A string with the event name.
func The function to call.

awesome.disconnect_signal (name, func)

Remove a global signal.

Parameters:

name A string with the event name.
func The function to call.

awesome.emit_signal (name, ...)

Emit a global signal.

Parameters:

name A string with the event name.
... The signal arguments.

awesome.spawn (cmd[, use_sn=true[, stdin=false[, stdout=false[, stderr=false[, exit_callback=nil[, cmd=nil]]]]]]) -> (integer, string, integer, integer, integer) or string

Spawn a program. The program will be started on the default screen.

Parameters:

cmd table The environment to use for the spawned program. Without this the spawned process inherits awesome's environment. (default nil)
use_sn boolean Use startup-notification? (default true)
stdin boolean Return a fd for stdin? (default false)
stdout boolean Return a fd for stdout? (default false)
stderr boolean Return a fd for stderr? (default false)
exit_callback function Function to call on process exit. The function arguments will be type of exit ("exit" or "signal") and the exit code / the signal number causing process termination. (default nil)
cmd table The environment to use for the spawned program. Without this the spawned process inherits awesome's environment. (default nil)

Returns:

integer Process ID if everything is OK.
string Startup-notification ID, if use_sn is true.
integer stdin, if stdin is true.
integer stdout, if stdout is true.
integer stderr, if stderr is true.

Or

string

awesome.xkb_set_layout_group (num)

Switch keyboard layout.

Parameters:

num integer keyboard layout number, integer from 0 to 3

awesome.xkb_get_layout_group () -> integer

Get current layout number.

Returns:

integer

awesome.xkb_get_group_names () -> string

Get layout short names.

Returns:

string

shift

Signals

debug::error

A call into the Lua code aborted with an error.

This signal is used in the example configuration, 05-awesomerc.md, to let a notification box pop up.

Arguments:

err Table with the error object, can be converted to a string with tostring(err).

debug::deprecation

A deprecated Lua function was called.

Arguments:

hint string String with a hint on what to use instead of the deprecated functionality.
see string or nil The name of the newer API (default nil)
args table or nil The name of the newer API (default nil)

debug::index::miss

An invalid key was read from an object.

This can happen if foo in an c.foo access does not exist.

Arguments:

unknown1 Class?
unknown2 Key?

debug::newindex::miss

An invalid key was written to an object.

This can happen if foo in an c.foo = "bar" assignment doesn't exist.

Arguments:

unknown1 Class?
unknown2 Key?
unknown3 Value?

systray::update

The systray should be updated.

This signal is used in wibox.widget.systray.

wallpaper_changed

The wallpaper has changed.

This signal is used for pseudo-transparency in wibox.drawable if no composite manager is running.

xkb::map_changed

Keyboard map has changed.

This signal is sent after the new keymap has been loaded. It is used in awful.widget.keyboardlayout to redraw the layout.

xkb::group_changed.

Keyboard group has changed.

It's used in awful.widget.keyboardlayout to redraw the layout.

Arguments:

group Integer containing the changed group

refresh

Refresh.

This signal is emitted as a kind of idle signal in the event loop. One example usage is in gears.timer to executed delayed calls.

startup

AwesomeWM is about to enter the event loop.

This means all initialization has been done.

exit

AwesomeWM is exiting / about to restart.

This signal is emitted in the atexit handler as well when awesome restarts.

Arguments:

reason_restart Boolean value is true if the signal was sent because of a restart.

screen::change

The output status of a screen has changed.

Arguments:

output string String containing which output has changed.
connection_state string String containing the connection status of the output: It will be either "Connected", "Disconnected" or "Unknown".

spawn::canceled

For some reason the application aborted startup

Arguments:

arg Table which only got the "id" key set

spawn::change

When one of the fields from the spawn::initiated table changes

Arguments:

arg Table which describes the spawn event

spawn::completed

An application finished starting

Arguments:

arg Table which only got the "id" key set

spawn::initiated

When a new client is beginning to start

Arguments:

arg Table which describes the spawn event

spawn::timeout

An application started a spawn event but didn't start in time.

Arguments:

arg Table which only got the "id" key set

Fields

awesome.version string

The AwesomeWM version.

awesome.release string

The AwesomeWM release name.

awesome.api_level string

The AwesomeWM API level.

By default, this matches the major version (first component of the version).

API levels are used to allow newer version of AwesomeWM to alter the behavior and subset deprecated APIs. Using an older API level than the current major version allows to use legacy rc.lua with little porting. However, they won't be able to use all the new features. Attempting to use a newer feature along with an older API level is not and will not be supported, even if it almost works. Keeping up to date with the newer API levels is highly recommended.

Going the other direction, setting an higher API level allows to take advantage of experimental feature. It will also be much harsher when it comes to deprecation. Setting the API level value beyond current+3 will treat using APIs currently pending deprecation as fatal errors. All new code submitted to the upstream AwesomeWM codebase is forbidden to use deprecated APIs. Testing your patches with mode and the default config is recommended before submitting a patch.

You can use the -l command line option or api-level modeline key to set the API level for your rc.lua. This setting is global and read only, individual modules cannot set their own API level.

awesome.conffile string

The configuration file which has been loaded.

awesome.startup boolean

True if we are still in startup, false otherwise.

awesome.startup_errors string

Error message for errors that occurred during startup.

awesome.composite_manager_running boolean

True if a composite manager is running.

awesome.unix_signal table

Table mapping between signal numbers and signal identifiers.

awesome.hostname string

The hostname of the computer on which we are running.

awesome.themes_path string

The path where themes were installed to.

awesome.icon_path string

The path where icons were installed to.

awesome.mainloop_timestamp number

A low-precision timestampt of when the last even loop iteration was started.

It is a floating point number with the number of seconds since 1970.

awesome

Contents

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: awesome

Info:

Static module functions

Signals

Fields

Static module functions

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Or

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Or

Parameters:

Returns:

Returns:

Signals

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Fields

Module: `awesome`