# Module `root`

awesome root window API

### Info:

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

## Functions

fake_input (event_type, detail, x, y) | Send fake keyboard or mouse events.
keys (keys_array) | Get or set global key bindings.
buttons (button_table) | Get or set global mouse bindings.
cursor (cursor_name) | Set the root cursor
drawins () | Get the drawins attached to a screen.
wallpaper (pattern) | Get the wallpaper as a cairo surface or set it as a cairo pattern.
size () | Get the size of the root window.
size_mm () | Get the physical size of the root window, in millimeter.
tags () | Get the attached tags.

## Functions

Methods

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:

      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)

  - 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.
keys (keys_array)
  Get or set global key bindings. These bindings will be available when you press keys on the root window.
  - keys_array table or nil An array of key binding objects, or nothing.

  ### Returns:

  The array of key bindings objects of this client.
buttons (button_table)
  Get or set global mouse bindings. This binding will be available when you click on the root window.
  - button_table An array of mouse button bindings objects, or nothing.

  ### Returns:

  The array of mouse button bindings objects.
cursor (cursor_name)

  Set the root cursor The possible values are:

  - num_glyphs
    cursor
    arrow
    basedarrowdown
    basedarrowup
    boat
    bogosity
    bottomleftcorner
    bottomrightcorner
    bottom_side
    bottom_tee
    box_spiral
    center_ptr
    circle
    clock
    coffee_mug
    cross
    cross_reverse
    crosshair
    diamond_cross
    dot
    dotbox
    double_arrow
    draft_large
    draft_small
    draped_box
    exchange
    fleur
    gobbler
    gumby
    hand
    hand
    heart
    icon
    iron_cross
    left_ptr
    left_side
    left_tee
    leftbutton
    ll_angle
    lr_angle
    man
    middlebutton
    mouse
    pencil
    pirate
    plus
    question_arrow
    right_ptr
    right_side
    right_tee
    rightbutton
    rtl_logo
    sailboat
    sbdownarrow
    sbhdouble_arrow
    sbleftarrow
    sbrightarrow
    sbuparrow
    sbvdouble_arrow
    shuttle
    sizing
    spider
    spraycan
    star
    target
    tcross
    topleftarrow
    topleftcorner
    toprightcorner
    top_side
    top_tee
    trek
    ul_angle
    umbrella
    ur_angle
    watch
    xterm

  - cursor_name A X cursor name.
drawins ()
  Get the drawins attached to a screen.

  ### Returns:

  A table with all drawins.
wallpaper (pattern)
  Get the wallpaper as a cairo surface or set it as a cairo pattern.
  - pattern A cairo pattern as light userdata

  ### Returns:

  A cairo surface or nothing.
size ()
  Get the size of the root window.

  ### Returns:

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

  ### Returns:

  1. Width of the root window, in millimeters.
  2. height of the root window, in millimeters.
tags ()
  Get the attached tags.

  ### Returns:

  A table with all tags.

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