Module: root
awesome root window API.
Info:
- Copyright: 2008-2009 Julien Danjou
- Author: Julien Danjou <julien@danjou.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 () -> () | 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). | |
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
keygrabberor 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)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 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
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:
- Width of the root window.
- height of the root window.
- root.size_mm () -> ()
-
Get the physical size of the root window, in millimeter.
Returns:
- Width of the root window, in millimeters.
- 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), }