# Module: `root`

APIs to interact with the root window.

X11 windows (clients) are stored in a tree. Each window can have children. A common example of this are modal dialog windows.

This tree goes beyond a process. The root window is where the wallpaper is drawn. It span the combined geometry of every screen. It also persist when AwesomeWM is restarted.

### 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

root.fake_input (event_type, detail, x, y) | Send fake keyboard or mouse events. |
root.cursor (cursor_name) | Set the root cursor |
root.drawins () -> table | Get the drawins attached to a screen. |
root.size () -> (integer, integer) | Get the size of the root window. |
root.size_mm () -> (integer, integer) | Get the physical size of the root window, in millimeter. |
root.tags () -> table | Get the attached tags. |

## Object properties

keys | table | Get or set global key bindings. |
buttons | table | Store the list of mouse buttons to be applied on the wallpaper (also known as root window). |
content | raw_surface | Get the content of the root window as a cairo surface. |

## Deprecated functions

root.wallpaper (pattern) | Get the wallpaper as a cairo surface or set it as a cairo pattern. | Deprecated

## Static module functions

🔗 root.fake_input (event_type, detail, x, y)
  Send fake keyboard or mouse events.

  Usually the currently focused client or the keybindings will receive those events. If a `keygrabber` or mousegrabber is running, then it will get them.

  Some keys have different names compared to the ones generally used in Awesome. For example, Awesome uses "modifier keys" for keybindings using their X11 names such as "Control" or "Mod1" (for "Alt"). These are not the name of the key but is only the name of the modifier they represent. Some modifiers are even present twice on some keyboard like the left and right "Shift". Here is a list of the "real" key names matching the modifiers in fake_input:

  Modifier name | Key name | Other key name
  --- | --- | ---
  Mod4 | Super_L | Super_R
  Control | Control_L | Control_R
  Shift | Shift_L | Shift_R
  Mod1 | Alt_L | Alt_R

  Note that this is valid for most of the modern "western" keyboard layouts. Some older, custom or foreign layouts may break this convention.

  This function is very low level, to be more useful, it can be wrapped into higher level constructs such as:

  **Sending strings:**

  local function send_string_to_client(s, c) local old_c = client.focus client.focus = c for i=1, #s do local char = s:sub(i,i) root.fake_input("key_press" , char) root.fake_input("key_release", char) end client.focus = old_c end send_string_to_client("Hello world!")

  Note that this example works for most ASCII inputs but may fail depending on how the string is encoded. Some multi-byte characters may not represent keys and some UTF-8 encoding format create characters by combining multiple elements such as accent + base character or various escape sequences. If you wish to use this example for "real world" i18n use cases, learning about XKB event and UTF-8 encoding is a prerequisites.

  **Clicking:**

  ![Client geometry](../images/mouse.svg)

  local function click(button_id, x, y) mouse.coords {x = x, y = y} root.fake_input("button_press" , button_id) root.fake_input("button_release", button_id) end click(1, 42, 42)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  event_type |  |  | The event type: key\_press, key\_release, button\_press, button\_release or motion\_notify.
  detail |  |  | The detail: in case of a key event, this is the keycode to send, in case of a button event this is the number of the button. In case of a motion event, this is a boolean value which if true makes the coordinates relatives.
  x |  |  | In case of a motion event, this is the X coordinate.
  y |  |  | In case of a motion event, this is the Y coordinate.

🔗 root.cursor (cursor_name)
  Set the root cursor The possible values are:

  num\_glyphs
  arrow
  based\_arrow\_down
  based\_arrow\_up
  boat
  bogosity
  bottom\_left\_corner
  bottom\_right\_corner
  bottom\_side
  bottom\_tee
  box\_spiral
  center\_ptr
  circle
  clock
  coffee\_mug
  cross
  crosshair
  cross\_reverse
  cursor
  diamond\_cross
  dotbox
  dot
  double\_arrow
  draft\_large
  draft\_small
  draped\_box
  exchange
  fleur
  gobbler
  gumby
  hand
  hand
  heart
  icon
  iron\_cross
  leftbutton
  left\_ptr
  left\_side
  left\_tee
  ll\_angle
  lr\_angle
  man
  middlebutton
  mouse
  pencil
  pirate
  plus
  question\_arrow
  rightbutton
  right\_ptr
  right\_side
  right\_tee
  rtl\_logo
  sailboat
  sb\_down\_arrow
  sb\_h\_double\_arrow
  sb\_left\_arrow
  sb\_right\_arrow
  sb\_up\_arrow
  sb\_v\_double\_arrow
  shuttle
  sizing
  spider
  spraycan
  star
  target
  tcross
  top\_left\_arrow
  top\_left\_corner
  top\_right\_corner
  top\_side
  top\_tee
  trek
  ul\_angle
  umbrella
  ur\_angle
  watch
  xterm

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cursor_name |  | string | A X cursor name.

🔗 root.drawins () -> table
  Get the drawins attached to a screen.

  ### Returns:

  table A table with all drawins.
🔗 root.size () -> (integer, integer)
  Get the size of the root window.

  ### Returns:

  1. integer Width of the root window.
  2. integer height of the root window.
🔗 root.size_mm () -> (integer, integer)
  Get the physical size of the root window, in millimeter.

  ### Returns:

  1. integer Width of the root window, in millimeters.
  2. integer height of the root window, in millimeters.
🔗 root.tags () -> table
  Get the attached tags.

  ### Returns:

  table A table with all tags.

## Object properties

🔗 keys table
  Get or set global key bindings. These bindings will be available when you press keys on the root window (the wallpaper).

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of awful.key objects.

  ### See also:

  awful.key | Create easily new key objects ignoring certain modifiers. | module

🔗 buttons table
  Store the list of mouse buttons to be applied on the wallpaper (also known as root window).

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of awful.button objects.

  ### See also:

  awful.button | Create easily new buttons objects ignoring certain modifiers. | module

  ### Usage:

      root.buttons = {
          awful.button({ }, 3, function () mymainmenu:toggle() end),
          awful.button({ }, 4, awful.tag.viewnext),
          awful.button({ }, 5, awful.tag.viewprev),
      }

🔗 content raw_surface
  Get the content of the root window as a cairo surface.

  ### Constraints:

  Default value | : This is the live content. Use `gears.surface(root.content)` to take a screenshot.
  Valid values | : A cairo surface with the root window content (aka the whole surface from every screens).

  ### See also:

  gears.surface | Utilities to integrate and manipulate Cairo drawing surfaces. | module

## Deprecated functions

🔗 root.wallpaper (pattern)
  Get the wallpaper as a cairo surface or set it as a cairo pattern.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  pattern |  |  | A cairo pattern as light userdata

  ### Returns:

  A cairo surface or nothing.

  ### See also:

  awful.wallpaper | Allows to use the wibox widget system to draw the wallpaper. | module

generated by LDoc 1.5.0