# Module: `awful.permissions`

Default implementation of the various requests handers.

AwesomeWM has many `request::` signals across the core APIs. They help decouple the default behavior from the core API. The request handlers can be disconnected and replaced by module or rc.lua to alter AwesomeWM behavior.

This module provides the default implementation of those request handlers. Beside some legacy signals, most request handlers have a main object, a named context and a table containing any low-level hints the core code is aware of. Each default handler implement a context based filter mechanism. This filter is called the "permissions". It allows requests to be denied. For example, if a tiled client asks to be resized or moved, the permission and deny it. In the documentation, many objects and properties have a "permissions" section you can display by clicking "show more".

### Info:

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

## Static module functions

awful.permissions.add_activate_filter (f, context) | Add an activate (focus stealing) filter function. |
awful.permissions.remove_activate_filter (f, context) -> boolean | Remove an activate (focus stealing) filter function. |

## Request handlers

awful.permissions.activate (c, context, hints) | Activate a window. |
awful.permissions.tag (c, t, hints) | Tag a window with its requested tag. |
awful.permissions.urgent (c, urgent) | Handle client urgent request |
awful.permissions.geometry (c, context, hints) | Move and resize the client. |
awful.permissions.wibox_geometry (w, context, hints) | Move and resize the wiboxes. |
awful.permissions.merge_maximization (c, context, hints) | Merge the 2 requests sent by clients wanting to be maximized. |
awful.permissions.client_geometry_requests (c, context, hints) | Allow the client to move itself. |
awful.permissions.update_border (c, context) | The default client `request::border` handler. |
awful.permissions.autoactivate (c, context, hints) | Default handler for the `request::autoactivate` signal. |

## Theme variables

beautiful.maximized_honor_padding | boolean | Honor the screen padding when maximizing. |
beautiful.fullscreen_hide_border | boolean | Hide the border on fullscreen clients. |
beautiful.maximized_hide_border | boolean | Hide the border on maximized clients. |

## Tables

awful.permissions.generic_activate_filters | The list of all registered generic `request::activate` (focus stealing) filters. |
awful.permissions.contextual_activate_filters | The list of all registered contextual `request::activate` (focus stealing) filters. |

## Static module functions

🔗 awful.permissions.add_activate_filter (f, context)
  Add an activate (focus stealing) filter function.

  The callback takes the following parameters:

  * **c** (*client*) The client requesting the activation * **context** (*string*) The activation context. * **hints** (*table*) Some additional hints (depending on the context)

  If the callback returns `true`, the client will be activated. If the callback returns `false`, the activation request is cancelled unless the `force` hint is set. If the callback returns `nil`, the previous callback will be executed. This will continue until either a callback handles the request or when it runs out of callbacks. In that case, the request will be granted if the client is visible.

  For example, to block Firefox from stealing the focus, use:

  awful.permissions.add_activate_filter(function(c) if c.class == "Firefox" then return false end end)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  f |  | function | The callback
  context | Optional | string | The `request::activate` context

  ### See also:

  awful.permissions.generic_activate_filters | The list of all registered generic `request::activate` (focus stealing) filters. | tables
  awful.permissions.contextual_activate_filters | The list of all registered contextual `request::activate` (focus stealing) filters. | tables
  awful.permissions.remove_activate_filter | Remove an activate (focus stealing) filter function. | static module functions

🔗 awful.permissions.remove_activate_filter (f, context) -> boolean
  Remove an activate (focus stealing) filter function. This is an helper to avoid dealing with permissions.add_activate_filter directly.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  f |  | function | The callback
  context | Optional | string | The `request::activate` context

  ### Returns:

  boolean If the callback existed

  ### See also:

  awful.permissions.generic_activate_filters | The list of all registered generic `request::activate` (focus stealing) filters. | tables
  awful.permissions.contextual_activate_filters | The list of all registered contextual `request::activate` (focus stealing) filters. | tables
  awful.permissions.add_activate_filter | Add an activate (focus stealing) filter function. | static module functions

## Request handlers

🔗 awful.permissions.activate (c, context, hints)
  Activate a window.

  This sets the focus only if the client is visible. If `raise` is set in the hints, it will also unminimize the client and move it to the top of its layer.

  It is the default signal handler for `request::activate` on a client.

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | A client to use | Not applicable
  context |  | string | The context where this signal was used. | Not applicable
  hints | Optional | table | A table with additional hints: | Undefined
  raise | Optional | boolean | Should the client be unminimized and raised? | `false`
  switch_to_tag | Optional | boolean | Should the client's first tag be selected if none of the client's tags are selected? | `false`
  switch_to_tags | Optional | boolean | Select all tags associated with the client. | `false`

  Click to display more

  ### Source signal:

  `request::activate` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::activate', awful.permissions.activate)

      -- Connect a custom handler.
      client.connect_signal('request::activate', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.tag (c, t, hints)
  Tag a window with its requested tag.

  It is the default signal handler for `request::tag` on a client.

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | A client to tag | Not applicable
  t | Optional | awful.permissions.tag or boolean | A tag to use. If `true`, then the client is made `sticky`. | Undefined
  hints | Optional | table | Extra information. | `{}`
  reason | Optional | nil or string | Why the tag is being changed. | `nil`

  Click to display more

  ### Source signal:

  `request::tag` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::tag', awful.permissions.tag)

      -- Connect a custom handler.
      client.connect_signal('request::tag', function(c, tag, hints)
          -- code here
      end)

🔗 awful.permissions.urgent (c, urgent)
  Handle client urgent request

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  c |  | client | A client
  urgent |  | boolean | If the client should be urgent

  Click to display more

  ### Source signal:

  `request::urgent` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::urgent', awful.permissions.urgent)

      -- Connect a custom handler.
      client.connect_signal('request::urgent', function(c)
          -- code here
      end)

🔗 awful.permissions.geometry (c, context, hints)
  Move and resize the client.

  This is the default geometry request handler.

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | The client | Not applicable
  context |  | string | The context | Not applicable
  hints | Optional | table | The hints to pass to the handler | `{}`
  store_geometry | Optional | boolean | Create a memento of the previous geometry in case it has to be restored. | `true`
  honor_workarea | Optional | boolean | Avoid overlapping the wibars or other desktop decoration when applying the geometry. | `true`

  Click to display more

  ### Source signal:

  `request::geometry` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::geometry', awful.permissions.geometry)

      -- Connect a custom handler.
      client.connect_signal('request::geometry', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.wibox_geometry (w, context, hints)
  Move and resize the wiboxes.

  This is the default geometry request handler.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  w |  | wibox | The wibox.
  context |  | string | The context
  hints | Optional | table | The hints to pass to the handler
  x | Optional | integer | The horizontal position.
  y | Optional | integer | The vertical position.
  width | Optional | integer | The wibox width.
  height | Optional | integer | The wibox height.

  Click to display more

  ### Source signal:

  `request::geometry` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::geometry', awful.permissions.wibox_geometry)

      -- Connect a custom handler.
      client.connect_signal('request::geometry', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.merge_maximization (c, context, hints)
  Merge the 2 requests sent by clients wanting to be maximized.

  The X clients set 2 flags (atoms) when they want to be maximized. This caused 2 `request::geometry` to be sent. This code gives some time for them to arrive and send a new `request::geometry` (through the property change) with the combined state.

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | The client | Not applicable
  context |  | string | The context | Not applicable
  hints | Optional | table | The hints to pass to the handler. | `{}`
  toggle | Optional | boolean | Toggle the maximization state rather than set it to `true`. | `false`

  Click to display more

  ### Source signal:

  `request::geometry` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::geometry', awful.permissions.merge_maximization)

      -- Connect a custom handler.
      client.connect_signal('request::geometry', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.client_geometry_requests (c, context, hints)
  Allow the client to move itself.

  This is the default geometry request handler when the context is permissions.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  c |  | client | The client
  context |  | string | The context
  hints | Optional | table | The hints to pass to the handler.
  x | Optional | integer | The horizontal position.
  y | Optional | integer | The vertical position.
  width | Optional | integer | The client width.
  height | Optional | integer | The client height.

  Click to display more

  ### Source signal:

  `request::geometry` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::geometry', awful.permissions.client_geometry_requests)

      -- Connect a custom handler.
      client.connect_signal('request::geometry', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.update_border (c, context) · 58 theme variables
  The default client `request::border` handler.

  To replace this handler with your own, use:

  client.disconnect_signal("request::border", awful.permisions.update_border)

  The default implementation chooses from dozens beautiful theme variables depending if the client is tiled, floating, maximized and then from its state (urgent, new, active, normal)

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  c |  | client | The client.
  context |  | string | Why is the border changed.

  ### See also:

  client.border_width | The client border width. (client) | object properties
  client.border_color | The client border color. (client) | object properties

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  `beautiful.border_color_marked` |
  `beautiful.border_color_active` |
  `beautiful.border_color_normal` |
  `beautiful.border_color_new` |
  `beautiful.border_color_urgent` |
  `beautiful.border_color_floating` |
  `beautiful.border_color_floating_active` |
  `beautiful.border_color_floating_normal` |
  `beautiful.border_color_floating_new` |
  `beautiful.border_color_floating_urgent` |
  `beautiful.border_color_maximized` |
  `beautiful.border_color_maximized_active` |
  `beautiful.border_color_maximized_normal` |
  `beautiful.border_color_maximized_new` |
  `beautiful.border_color_maximized_urgent` |
  `beautiful.border_color_fullscreen` |
  `beautiful.border_color_fullscreen_active` |
  `beautiful.border_color_fullscreen_normal` |
  `beautiful.border_color_fullscreen_new` |
  `beautiful.border_color_fullscreen_urgent` |
  `beautiful.border_width_active` |
  `beautiful.border_width_normal` |
  `beautiful.border_width_new` |
  `beautiful.border_width_urgent` |
  `beautiful.border_width_floating` |
  `beautiful.border_width_floating_active` |
  `beautiful.border_width_floating_normal` |
  `beautiful.border_width_floating_new` |
  `beautiful.border_width_floating_urgent` |
  `beautiful.border_width_maximized` |
  `beautiful.border_width_maximized_active` |
  `beautiful.border_width_maximized_normal` |
  `beautiful.border_width_maximized_new` |
  `beautiful.border_width_maximized_urgent` |
  `beautiful.border_width_fullscreen` |
  `beautiful.border_width_fullscreen_active` |
  `beautiful.border_width_fullscreen_normal` |
  `beautiful.border_width_fullscreen_new` |
  `beautiful.border_width_fullscreen_urgent` |
  `beautiful.opacity_floating` |
  `beautiful.opacity_floating_active` |
  `beautiful.opacity_floating_normal` |
  `beautiful.opacity_floating_new` |
  `beautiful.opacity_floating_urgent` |
  `beautiful.opacity_maximized` |
  `beautiful.opacity_maximized_active` |
  `beautiful.opacity_maximized_normal` |
  `beautiful.opacity_maximized_new` |
  `beautiful.opacity_maximized_urgent` |
  `beautiful.opacity_fullscreen` |
  `beautiful.opacity_fullscreen_active` |
  `beautiful.opacity_fullscreen_normal` |
  `beautiful.opacity_fullscreen_new` |
  `beautiful.opacity_fullscreen_urgent` |
  `beautiful.opacity_active` |
  `beautiful.opacity_normal` |
  `beautiful.opacity_new` |
  `beautiful.opacity_urgent` |

  ### Source signal:

  `request::border` from the client module. This code allows to disconnect this handler and implement your own:

      -- Disconnect the original handler.
      client.disconnect_signal('request::border', awful.permissions.update_border)

      -- Connect a custom handler.
      client.connect_signal('request::border', function(c, context, hints)
          -- code here
      end)

🔗 awful.permissions.autoactivate (c, context, hints)
  Default handler for the `request::autoactivate` signal.

  All it does is to emit `request::activate` with the following context mapping:

  * mouse_enter: *mouse.enter* * switch_tag : *autofocus.check_focus_tag* * history : *autofocus.check_focus*

  ### Arguments:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | The client. | Not applicable
  context |  | string | Why is the client auto-activated. | Not applicable
  hints | Optional | table | Extra arguments. | `{}`

  ### See also:

  awful.permissions.activate | Activate a window. | request handlers
  client:activate | Activate (focus) a client. (client) | object methods

  ### Source signal:

  `request::activated` from the client module. This code allows to disconnect this handler and implement your own:

## Theme variables

🔗 beautiful.maximized_honor_padding boolean
  Honor the screen padding when maximizing.
  Click to display more

  ### Used by:

  - `padding` The screen padding.
🔗 beautiful.fullscreen_hide_border boolean
  Hide the border on fullscreen clients.
  Click to display more

  ### Used by:

  - `border_width` The client border width.
🔗 beautiful.maximized_hide_border boolean
  Hide the border on maximized clients.
  Click to display more

  ### Used by:

  - `border_width` The client border width.

## Tables

🔗 awful.permissions.generic_activate_filters
  The list of all registered generic `request::activate` (focus stealing) filters. If a filter is added to only one context, it will be in permissions.contextual_activate_filters["context_name"].

  ### See also:

  permissions.activate | Activate a window. | request handlers
  permissions.add_activate_filter | Add an activate (focus stealing) filter function. | static module functions
  permissions.remove_activate_filter | Remove an activate (focus stealing) filter function. | static module functions

🔗 awful.permissions.contextual_activate_filters
  The list of all registered contextual `request::activate` (focus stealing) filters. If a filter is added to only one context, it will be in permissions.generic_activate_filters.

  ### See also:

  permissions.activate | Activate a window. | request handlers
  permissions.add_activate_filter | Add an activate (focus stealing) filter function. | static module functions
  permissions.remove_activate_filter | Remove an activate (focus stealing) filter function. | static module functions

generated by LDoc 1.5.0