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 <[email protected]>
(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 returnsfalse
, the activation request is cancelled unless theforce
hint is set. If the callback returnsnil
, 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
contextSee 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
contextReturns:
-
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 madesticky
.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 newrequest::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