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:

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, "permissions")

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
  • switchtag : *autofocus.checkfocus_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