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

Info:

Copyright: 2008-2009 Julien Danjou
Originally authored by: Julien Danjou <[email protected]>
(Full contributors list available on our github project)

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

🔗 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
wibox	geometry	mouse.move	granted	Requests 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.

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.

Parameters:

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

Parameters:

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

Emit signals:

client_mousebinding::added

button awful.button The button.

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

Parameters:

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

Returns:

boolean

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

x

y

buttons

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.

Constraints:

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

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.

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:

awful.mouse.snap Snap a client to the closest client or screen edge.

🔗 beautiful.snap_border_width integer

The snap outline width.
Click to display more

Used by:

awful.mouse.snap Snap a client to the closest client or screen edge.

🔗 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:

awful.mouse.snap Snap a client to the closest client or screen edge.

🔗 beautiful.snapper_gap number

The gap between snapped clients.
Click to display more

Used by:

awful.mouse.snap Snap a client to the closest client or screen edge.

🔗 beautiful.cursor_mouse_resize string

The resize cursor name.
Click to display more

Used by:

awful.mouse.resize Resize the drawable.

🔗 beautiful.cursor_mouse_move string

The move cursor name.
Click to display more

Used by:

awful.mouse.resize Resize the drawable.

Deprecated functions

🔗 awful.mouse.client_under_pointer ()

Get the client object under the pointer.

Returns:

client or nil

Fields

🔗 awful.mouse.snap.default_distance integer

The default distance before snapping clients together.

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
client	geometry	mouse.move	granted	When 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:

string The corner name
number x The horizontal position
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

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	mouse.resize	granted	When 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
wibox	geometry	mouse.resize	granted	Requests 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

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.snap_bg
beautiful.snap_border_width
beautiful.snap_shape
beautiful.snapper_gap

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

awesome

Contents

Input handling

Core components

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Libraries

Sample files

Classes

Documentation

Module: mouse

Info:

Static module functions

Returns:

Parameters:

Requested actions or permissions:

Parameters:

See also:

Parameters:

See also:

Parameters:

See also:

Parameters:

See also:

Emit signals:

Parameters:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Object properties

Constraints:

Constraints:

Constraints:

Constraints:

Constraints:

See also:

Constraints:

See also:

Constraints:

See also:

Constraints:

Constraints:

Constraints:

Theme variables

Used by:

Used by:

Type constraints:

Used by:

Used by:

Used by:

Used by:

Deprecated functions

Returns:

See also:

Fields

See also:

See also:

lib.awful.mouse.client Functions

Parameters:

Requested actions or permissions:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Requested actions or permissions:

lib.awful.mouse.resize Functions

Parameters:

Parameters:

Parameters:

Module: `mouse`