Module: mouse

Manipulate and inspect the mouse cursor.

The mouse buttons are represented as index. The common ones are:

Client geometry

It is possible to be notified of mouse events by connecting to various client, widgets and wibox signals:

  • mouse::enter
  • mouse::leave
  • mouse::press
  • mouse::release
  • mouse::move

It is also possible to add generic mouse button callbacks for clients, wiboxes and the root window. Those are set in the default rc.lua as such:

root:

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

client:

clientbuttons = awful.util.table.join(
    awful.button({ }, 1, function (c) client.focus = c; c:raise() end),
    awful.button({ modkey }, 1, awful.mouse.client.move),
    awful.button({ modkey }, 3, awful.mouse.client.resize)
)

See also mousegrabber

Info:

Static module functions

mouse.object_under_pointer () -> client or wibox or nil Get the client or any object which is under the pointer.
awful.mouse.wibox.move (w) Move the wibox under the cursor.
awful.mouse.append_global_mousebinding (button) Add an awful.button based mousebinding to the global set.
awful.mouse.append_global_mousebindings (buttons) Add multiple awful.button based mousebindings to the global set.
awful.mouse.remove_global_mousebinding (button) Remove a mousebinding from the global set.
awful.mouse.append_client_mousebinding (button) Add an awful.button to the default client buttons.
awful.mouse.append_client_mousebindings (buttons) Add a awful.buttons to the default client buttons.
awful.mouse.remove_client_mousebinding (button) -> boolean Remove a mousebinding from the default client buttons.
mouse.coords (coords_table, silent) -> table Get or set the mouse coords.

Object properties

screen screen or nil The screen under the cursor
current_client client or nil Get the client currently under the mouse cursor.
current_wibox wibox or nil Get the wibox currently under the mouse cursor.
current_widgets nil or table Get the widgets currently under the mouse cursor.
current_widget widget or nil Get the topmost widget currently under the mouse cursor.
current_widget_geometry table or nil Get the current widget geometry.
current_widget_geometries table or nil Get the current widget geometries.
is_left_mouse_button_pressed boolean True if the left mouse button is pressed.
is_right_mouse_button_pressed boolean True if the right mouse button is pressed.
is_middle_mouse_button_pressed boolean True if the middle mouse button is pressed.

Theme variables

beautiful.snap_bg color or string or gradient or pattern The snap outline background color.
beautiful.snap_border_width integer The snap outline width.
beautiful.snap_shape function The snap outline shape.
beautiful.snapper_gap number The gap between snapped clients.
beautiful.cursor_mouse_resize string The resize cursor name.
beautiful.cursor_mouse_move string The move cursor name.

Deprecated functions

awful.mouse.client_under_pointer () Get the client object under the pointer. Deprecated

Fields

awful.mouse.snap.default_distance integer The default distance before snapping clients together.
awful.mouse.snap.aerosnap_distance integer The default distance before activating screen edge snap.
awful.mouse.snap.edge_enabled boolean Enable screen edges snapping.
awful.mouse.snap.client_enabled boolean Enable client to client snapping.
awful.mouse.drag_to_tag.enabled boolean Enable changing tag when a client is dragged to the edge of the screen.

lib.awful.mouse.client Functions

awful.mouse.client.move (c, snap) Move a client.
awful.mouse.client.dragtotag.border (c) Move a client to a tag by dragging it onto the left / right side of the screen. Deprecated
awful.mouse.client.corner (c, corner) Get a client corner coordinates. Deprecated
awful.mouse.client.resize (c, corner, args) -> string Resize a client.

lib.awful.mouse.resize Functions

awful.mouse.resize.set_mode (m) Set the resize mode.
awful.mouse.resize.add_enter_callback (cb, context) Add an initialization callback.
awful.mouse.resize.add_move_callback (cb, context) Add a "move" callback.
awful.mouse.resize.add_leave_callback (cb, context) Add a "leave" callback This callback is executed just before the mousegrabber stop
awful.mouse.resize (client, context, args) Resize the drawable.

lib.awful.mouse.snap Functions

awful.mouse.snap (c, snap, x, y, fixed_x, fixed_y) Snap a client to the closest client or screen edge.


Static module functions

🔗 mouse.object_under_pointer () -> client or wibox or nil
Get the client or any object which is under the pointer.

Returns:

    client, wibox or nil A client, wibox or nil.
🔗 awful.mouse.wibox.move (w) · 1 permission
Move the wibox under the cursor.

Parameters:

Name Type(s) Description
w wibox The wibox to move, or none to use that under the pointer

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
wiboxgeometrymouse.movegrantedRequests to move the wibox.
🔗 awful.mouse.append_global_mousebinding (button)
Add an awful.button based mousebinding to the global set.

A global mousebinding is one which is always present, even when there is no focused client. If your intent is too add a mousebinding which acts on the focused client do not use this.

Parameters:

Name Type(s) Description
button awful.button The button object.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module
🔗 awful.mouse.append_global_mousebindings (buttons)
Add multiple awful.button based mousebindings to the global set.

A global mousebinding is one which is always present, even when there is no focused client. If your intent is too add a mousebinding which acts on the focused client do not use this

Parameters:

Name Type(s) Description
buttons table A table of awful.button objects. Optionally, it can have a group entry. If set, the group property will be set on all awful.buttons objects.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module
🔗 awful.mouse.remove_global_mousebinding (button)
Remove a mousebinding from the global set.

Parameters:

Name Type(s) Description
button awful.button The button object.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module
🔗 awful.mouse.append_client_mousebinding (button) · 1 signal
Add an awful.button to the default client buttons.

Parameters:

Name Type(s) Description
button awful.button The button.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module
awful.keyboard.append_client_keybinding Add an awful.key to the default client keys. (awful.keyboard) static module functions

Click to display more

Emit signals:

  • client_mousebinding::added
🔗 awful.mouse.append_client_mousebindings (buttons)
Add a awful.buttons to the default client buttons.

Parameters:

Name Type(s) Description
buttons table A table containing awful.button objects.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module
awful.keyboard.append_client_keybinding Add an awful.key to the default client keys. (awful.keyboard) static module functions
awful.mouse.append_client_mousebinding Add an awful.button to the default client buttons. static module functions
awful.keyboard.append_client_keybindings Add a awful.keys to the default client keys. (awful.keyboard) static module functions
🔗 awful.mouse.remove_client_mousebinding (button) -> boolean
Remove a mousebinding from the default client buttons.

Parameters:

Name Type(s) Description
button awful.button The button.

Returns:

    boolean True if the button was removed and false if it wasn't found.

See also:

awful.keyboard.append_client_keybinding Add an awful.key to the default client keys. (awful.keyboard) static module functions
🔗 mouse.coords (coords_table, silent) -> table

Get or set the mouse coords.

Usage example output:

235

Parameters:

Name Type(s) Description Default value
coords_table Optional table None or a table with x and y keys as mouse coordinates. nil
x Optional integer The mouse horizontal position nil
y Optional integer The mouse vertical position nil
silent Optional boolean Disable mouse::enter or mouse::leave events that could be triggered by the pointer when moving. false

Returns:

    table The coords. It contains the x, y and buttons keys. buttons contains the button number as key and a boolean as value (if it is pressed).

See also:

is_left_mouse_button_pressed True if the left mouse button is pressed. object properties
is_right_mouse_button_pressed True if the right mouse button is pressed. object properties
is_middle_mouse_button_pressed True if the middle mouse button is pressed. object properties

Usage:

    -- Get the position
    print(mouse.coords().x)
    -- Change the position
    mouse.coords {
        x = 185,
        y = 10
    }

Object properties

🔗 screen screen or nil
The screen under the cursor

Constraints:

Default value : It checks where the cursor is and match it to one of the screen geometry.
Type description:
nil : This will only happen if screen is set to off in the modeline or command line options. It happens very early in the initialization before the screens are created. If you check the screen from a signal, then you should never have to worry about this. Another corner case where this might happen is if you use fake_resize to have a smaller area than the physical screen.
screen : A valid screen object such as retured by awful.screen.focused() or mouse.screen.
integer : A screen global id. Avoid using this since they are unsorted.
string : The "primary" value is also valid.
🔗 current_client client or nil
Get the client currently under the mouse cursor.

Constraints:

Default value : nil
Type description:
nil : When the mouse cursor is not over a client.
🔗 current_wibox wibox or nil
Get the wibox currently under the mouse cursor.

Constraints:

Default value : nil
Type description:
nil : When the mouse cursor is not over a wibox.
🔗 current_widgets nil or table
Get the widgets currently under the mouse cursor.

Constraints:

Default value : nil
Type description:
nil : When the mouse cursor is not over any widget.
Table content : table The list of wibox.widgets. The first element is the biggest container while the last is the topmost widget.
🔗 current_widget widget or nil
Get the topmost widget currently under the mouse cursor.

Constraints:

Default value : nil
Type description:
nil : When the mouse cursor is not over a widget.

See also:

current_widget_geometry Get the current widget geometry. object properties
🔗 current_widget_geometry table or nil
Get the current widget geometry.

Constraints:

Default value : nil
Type description:
nil : When there is no current widgets.
table:
x (number)
y (number)
width (number)
height (number)

See also:

current_widget Get the topmost widget currently under the mouse cursor. object properties
🔗 current_widget_geometries table or nil
Get the current widget geometries.

Constraints:

Default value : nil
Type description:
nil : When there is no widgets.
table : A list of geometry tables.
Valid values : A list of geometry tables.

See also:

current_widgets Get the widgets currently under the mouse cursor. object properties
🔗 is_left_mouse_button_pressed boolean
True if the left mouse button is pressed.

Constraints:

Default value : false
Valid values : true or false.
🔗 is_right_mouse_button_pressed boolean
True if the right mouse button is pressed.

Constraints:

Default value : false
Valid values : true or false.
🔗 is_middle_mouse_button_pressed boolean
True if the middle mouse button is pressed.

Constraints:

Default value : false
Valid values : true or false.

Theme variables

🔗 beautiful.snap_bg color or string or gradient or pattern
The snap outline background color.
Click to display more

Used by:

🔗 beautiful.snap_border_width integer
The snap outline width.
Click to display more

Used by:

🔗 beautiful.snap_shape function
The snap outline shape.

Type constraints:

Name Type(s) Description
shape function A gears.shape compatible function

Click to display more

Used by:

🔗 beautiful.snapper_gap number
The gap between snapped clients.
Click to display more

Used by:

🔗 beautiful.cursor_mouse_resize string
The resize cursor name.
Click to display more

Used by:

🔗 beautiful.cursor_mouse_move string
The move cursor name.
Click to display more

Used by:

Deprecated functions

🔗 awful.mouse.client_under_pointer ()
Get the client object under the pointer.

Returns:

    client or nil The client object under the pointer, if one can be found.

See also:

current_client Get the client currently under the mouse cursor. object properties

Fields

🔗 awful.mouse.snap.default_distance integer
The default distance before snapping clients together.

See also:

awful.mouse.snap Snap a client to the closest client or screen edge. lib.awful.mouse.snap functions
🔗 awful.mouse.snap.aerosnap_distance integer
The default distance before activating screen edge snap.

See also:

awful.mouse.snap Snap a client to the closest client or screen edge. lib.awful.mouse.snap functions
🔗 awful.mouse.snap.edge_enabled boolean
Enable screen edges snapping.

🔗 awful.mouse.snap.client_enabled boolean
Enable client to client snapping.
🔗 awful.mouse.drag_to_tag.enabled boolean
Enable changing tag when a client is dragged to the edge of the screen.

lib.awful.mouse.client Functions

🔗 awful.mouse.client.move (c, snap) · 1 permission
Move a client.

Parameters:

Name Type(s) Description
c client The client to move, or the focused one if nil.
snap The pixel to snap clients.

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
clientgeometrymouse.movegrantedWhen awful.mouse.client.move is called.
🔗 awful.mouse.client.dragtotag.border (c)
Move a client to a tag by dragging it onto the left / right side of the screen.

Parameters:

Name Type(s) Description
c The client to move
🔗 awful.mouse.client.corner (c, corner)
Get a client corner coordinates.

Parameters:

Name Type(s) Description Default value
c Optional client The client to get corner from, focused one by default. client.focus
corner string The corner to use: auto, top_left, top_right, bottom_left, bottom_right, left, right, top or bottom. Default is auto. auto finds the nearest corner. Not applicable

Returns:

  1. string The corner name
  2. number x The horizontal position
  3. number y The vertical position
🔗 awful.mouse.client.resize (c, corner, args) -> string · 1 permission
Resize a client.

Parameters:

Name Type(s) Description Default value
c The client to resize, or the focused one by default. Not applicable
corner string The corner to grab on resize. Auto detected by default. Not applicable
args Optional table A set of awful.placement arguments {}

Returns:

    string The corner (or side) name

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
clientgeometrymouse.resizegrantedWhen awful.mouse.client.resize is called.

lib.awful.mouse.resize Functions

🔗 awful.mouse.resize.set_mode (m)
Set the resize mode. The available modes are:

  • live: Resize the layout everytime the mouse moves.
  • after: Resize the layout only when the mouse is released.

Some clients, such as XTerm, may lose information if resized too often.

Parameters:

Name Type(s) Description
m string The mode
🔗 awful.mouse.resize.add_enter_callback (cb, context)
Add an initialization callback. This callback will be executed before the mouse grabbing starts.

Parameters:

Name Type(s) Description Default value
cb function The callback (or nil) Not applicable
context Optional string The callback context "other"
🔗 awful.mouse.resize.add_move_callback (cb, context)
Add a "move" callback. This callback is executed in "after" mode (see set_mode) instead of applying the operation.

Parameters:

Name Type(s) Description Default value
cb function The callback (or nil) Not applicable
context Optional string The callback context "other"
🔗 awful.mouse.resize.add_leave_callback (cb, context)
Add a "leave" callback This callback is executed just before the mousegrabber stop

Parameters:

Name Type(s) Description Default value
cb function The callback (or nil) Not applicable
context Optional string The callback context "other"
🔗 awful.mouse.resize (client, context, args) · 2 theme variables · 1 permission

Resize the drawable.

Valid args are:

  • *enter_callback*: A function called before the mousegrabber starts.
  • *move_callback*: A function called when the mouse moves.
  • *leave_callback*: A function called before the mousegrabber is released.
  • mode: The resize mode.

Parameters:

Name Type(s) Description Default value
client client A client. Not applicable
context Optional string The resizing context. mouse.resize
args Optional table A set of awful.placement arguments. {}

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.cursor_mouse_move
beautiful.cursor_mouse_resize

Requested actions or permissions:

Class Permission Context Default Description
wiboxgeometrymouse.resizegrantedRequests to resize the wibox.

lib.awful.mouse.snap Functions

🔗 awful.mouse.snap (c, snap, x, y, fixed_x, fixed_y) · 4 theme variables
Snap a client to the closest client or screen edge.

Parameters:

Name Type(s) Description Default value
c Optional client The client to snap. client.focus
snap integer The pixel to snap clients. Not applicable
x integer The client x coordinate. Not applicable
y integer The client y coordinate. Not applicable
fixed_x boolean True if the client isn't allowed to move in the x direction. Not applicable
fixed_y boolean True if the client isn't allowed to move in the y direction. Not applicable

Returns:

    table The new geometry.

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.snap_bg
beautiful.snap_border_width
beautiful.snap_shape
beautiful.snapper_gap
generated by LDoc 1.5.0