Module: root

awesome root window API.

Info:

  • Copyright: 2008-2009 Julien Danjou
  • Originally authored by: Julien Danjou <julien@danjou.info>
    (Full contributors list available on our github project)

Functions

root.set_xproperty (name, value) Change a xproperty.
root.get_xproperty (name) Get the value of a xproperty.

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 () -> () Get the drawins attached to a screen.
root.wallpaper (pattern) -> () Get the wallpaper as a cairo surface or set it as a cairo pattern.
root.size () -> () Get the size of the root window.
root.size_mm () -> () Get the physical size of the root window, in millimeter.
root.tags () -> () 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 surface Get the content of the root window as a cairo surface.


Functions

Methods
root.set_xproperty (name, value)
Change a xproperty.

Parameters:

  • name The name of the X11 property
  • value The new value for the property
root.get_xproperty (name)
Get the value of a xproperty.

Parameters:

  • name The name of the X11 property

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:

  • 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
basedarrowdown
basedarrowup
boat
bogosity
bottomleftcorner
bottomrightcorner
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
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

Parameters:

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

Returns:

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

Parameters:

  • pattern A cairo pattern as light userdata

Returns:

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

Returns:

  1. Width of the root window.
  2. height of the root window.
root.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.
root.tags () -> ()
Get the attached tags.

Returns:

    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).

See also:

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

Type constraints:

  • buttons table The list of buttons. (default {})

See also:

Usage:

    root.buttons = {
    awful.button({ }, 3, function () mymainmenu:toggle() end),
    awful.button({ }, 4, awful.tag.viewnext),
    awful.button({ }, 5, awful.tag.viewprev),
}
content surface
Get the content of the root window as a cairo surface.

Type constraints:

  • A surface cairo surface with the root window content (aka the whole surface from every screens).

See also:

generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50