# Module: `awesome`

AwesomeWM lifecycle and low-level APIs.

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) | 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) -> gears.surface | Translate a GdkPixbuf to a cairo image surface.. |
awesome.load_image (name) -> (gears.surface, nil 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, stdin, stdout, stderr, exit_callback, cmd) -> (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. |

## Static module functions

🔗 awesome.register_xproperty (name, type)
  Register a new xproperty.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the X11 property.
  type |  | string | One of "string", "number" or "boolean".

🔗 awesome.quit (code)
  Quit awesome.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  code | Optional | integer | The exit code to use when exiting. | `0`

🔗 awesome.exec (cmd)
  Execute another application, probably a window manager, to replace awesome.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cmd |  | string | The command line to execute.

🔗 awesome.restart ()
  Restart awesome.
🔗 awesome.kill (pid, sig) -> boolean
  Send a signal to a process.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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
🔗 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) -> gears.surface
  Translate a GdkPixbuf to a cairo image surface..

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  pixbuf |  |  | The pixbuf as a light user datum.
  path |  |  | The pixbuf origin path

  ### Returns:

  gears.surface A cairo surface as light user datum.
🔗 awesome.load_image (name) -> (gears.surface, nil or string)
  Load an image from a given path.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The file name.

  ### Returns:

  1. gears.surface A cairo surface as light user datum.
  2. nil or string The error message, if any.
🔗 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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  size |  | integer | The size of the icons in pixels.

🔗 awesome.connect_signal (name, func)
  Add a global signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | A string with the event name.
  func |  | function | The function to call.

🔗 awesome.disconnect_signal (name, func)
  Remove a global signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | A string with the event name.
  func |  | function | The function to call.

🔗 awesome.emit_signal (name, ...)
  Emit a global signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | function | A string with the event name.
  ... |  |  | The signal arguments.

🔗 awesome.spawn (cmd, use_sn, stdin, stdout, stderr, exit_callback, cmd) -> (integer, string, integer, integer, integer) or string
  Spawn a program. The program will be started on the default screen.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cmd | Optional | table | The environment to use for the spawned program. Without this the spawned process inherits awesome's environment. | `nil`
  use_sn | Optional | boolean | Use startup-notification? | `true`
  stdin | Optional | boolean or string | Pass `true` to return a fd for stdin. Use `"DEV_NULL"` to redirect to /dev/null, or `"INHERIT"` to inherit the parent's stdin. Implementation note: Pre-2.74 glib doesn't support *explicit* `DEV_NULL`. When `DEV_NULL` is passed on glib <2.74, Awesome will use glib's default behaviour. | `"DEV_NULL"`
  stdout | Optional | boolean or string | Pass `true` to return a fd for stdout. Use `"DEV_NULL"` to redirect to /dev/null, or `"INHERIT"` to inherit the parent's stdout. Implementation note: Pre-2.74 glib doesn't support *explicit* `INHERIT`. When `INHERIT` is passed on glib <2.74, Awesome will use glib's default behaviour. | `"INHERIT"`
  stderr | Optional | boolean or string | Pass `true` to return a fd for stderr. Use `"DEV_NULL"` to redirect to /dev/null, or `"INHERIT"` to inherit the parent's stderr. Implementation note: Pre-2.74 glib doesn't support *explicit* `INHERIT`. When `INHERIT` is passed on glib <2.74, Awesome will use glib's default behaviour. | `"INHERIT"`
  exit_callback | Optional | 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. | `nil`
  cmd | Optional | table | The environment to use for the spawned program. Without this the spawned process inherits awesome's environment. | `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.
🔗 awesome.xkb_set_layout_group (num)
  Switch keyboard layout.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  num |  | integer | Keyboard layout number, integer from 0 to 3

🔗 awesome.xkb_get_layout_group () -> integer
  Get current layout number.

  ### Returns:

  integer num Current layout number, integer from 0 to 3.
🔗 awesome.xkb_get_group_names () -> string
  Get layout short names.

  ### Returns:

  string A string describing the current layout settings, e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  err |  | table | Table with the error object, can be converted to a string with `tostring(err)`.

🔗 debug::deprecation
  A deprecated Lua function was called.

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  hint |  | string | String with a hint on what to use instead of the deprecated functionality. | Not applicable
  see | Optional | string or nil | The name of the newer API | `nil`
  args | Optional | table or nil | The name of the newer API | `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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  group |  | number | 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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  reason_restart |  | boolean | Boolean value is true if the signal was sent because of a restart.

🔗 screen::change
  The output status of a screen has changed.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  |  | Table which only got the "id" key set

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

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  |  | Table which describes the spawn event

🔗 spawn::completed
  An application finished starting

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  |  | Table which only got the "id" key set

🔗 spawn::initiated
  When a new client is beginning to start

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  |  | Table which describes the spawn event

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

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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.

generated by LDoc 1.5.0