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:

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

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