# Module: `mouse`

Manipulate and inspect the mouse cursor.

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

![Client geometry](../images/mouse.svg)

It is possible to be notified of mouse events by connecting to various client, `widget`s 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, `wiboxe`s 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:

- Copyright: 2008-2009 Julien Danjou
- Originally authored by: Julien Danjou <julien@danjou.info>
  (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 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
  --- | --- | --- | --- | ---
  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.

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

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

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

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