# Module `awesome`

awesome core API

Additionally to the classes described here, one can also use X properties as described in xproperties.

### Info:

- Copyright: 2008-2009 Julien Danjou
- Author: Julien Danjou <julien@danjou.info>

## Functions

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

version | The version of awesome.
release | The release name of awesome.
conffile | The configuration file which has been loaded.
startup | True if we are still in startup, false otherwise.
startup_errors | Error message for errors that occured during startup.
composite_manager_running | True if a composite manager is running.
unix_signal | Table mapping between signal numbers and signal identifiers.
hostname | The hostname of the computer on which we are running.
themes_path | The path where themes were installed to.
icon_path | The path where icons were installed to.

## Functions

Methods

register_xproperty (name, type)
  Register a new xproperty.
  - name string The name of the X11 property.
  - type string One of "string", "number" or "boolean".
quit ([code=0])
  Quit awesome.
  - code integer The exit code to use when exiting. (default 0)
exec (cmd)
  Execute another application, probably a window manager, to replace awesome.
  - cmd The command line to execute.
restart ()
  Restart awesome.
kill (pid, sig)
  Send a signal to a process.
  - 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 true if the signal was successfully sent, else false
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.
pixbuf_to_surface (pixbuf, path)
  Translate a GdkPixbuf to a cairo image surface..
  - pixbuf The pixbuf as a light user datum.
  - path The pixbuf origin path

  ### Returns:

  A cairo surface as light user datum.
load_image (name)
  Load an image from a given path.
  - name The file name.

  ### Returns:

  A cairo surface as light user datum.

  ### Or

  1. nil
  2. string Error message
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.

  - size The size of the icons in pixels.
connect_signal (name, func)
  Add a global signal.
  - name A string with the event name.
  - func The function to call.
disconnect_signal (name, func)
  Remove a global signal.
  - name A string with the event name.
  - func The function to call.
emit_signal (name, ...)
  Emit a global signal.
  - name A string with the event name.
  - ... The signal arguments.
spawn (cmd[, use_sn=true[, stdin=false[, stdout=false[, stderr=false[, exit_callback=nil[, cmd=nil]]]]]])
  Spawn a program. The program will be started on the default screen.
  - 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:

  1. integer Process ID if everything is OK.
  2. string Startup-notification ID, if `use_sn` is true.
  3. integer stdin, if `stdin` is true.
  4. integer stdout, if `stdout` is true.
  5. integer stderr, if `stderr` is true.

  ### Or

  string An error string if an error occurred.
xkb_set_layout_group (num)
  Switch keyboard layout.
  - num integer keyboard layout number, integer from 0 to 3
xkb_get_layout_group ()
  Get current layout number.

  ### Returns:

  integer num Current layout number, integer from 0 to 3.
xkb_get_group_names ()
  Get layout short names.

  ### Returns:

  string A string describing the current layout settings, e.g.: 'pc+us+de:2+inet(evdev)+group(altshifttoggle)+ctrl(nocaps)'

## 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
  Awesome is about to enter the event loop.

  This means all initialization has been done.

exit
  Awesome 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 containing which output has changed.
  - connection_state 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

version
  The version of awesome.
  - version string
release
  The release name of awesome.
  - release string
conffile
  The configuration file which has been loaded.
  - conffile string
startup
  True if we are still in startup, false otherwise.
  - startup boolean
startup_errors
  Error message for errors that occured during startup.
  - startup_errors string
composite_manager_running
  True if a composite manager is running.
  - composite_manager_running boolean
unix_signal
  Table mapping between signal numbers and signal identifiers.
  - unix_signal table
hostname
  The hostname of the computer on which we are running.
  - hostname string
themes_path
  The path where themes were installed to.
  - themes_path string
icon_path
  The path where icons were installed to.
  - icon_path string

generated by LDoc 1.5.0 Last updated 2025-09-26 21:04:17