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

Parameters:

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

Returns:

boolean

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.

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.	`{}`

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

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

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

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

awesome

Contents

Libraries

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Sample files

Classes

Documentation

Module: awful.permissions

Info:

Static module functions

Request handlers

Theme variables

Tables

Static module functions

Parameters:

See also:

Parameters:

Returns:

See also:

Request handlers

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

Source signal:

Arguments:

See also:

Consumed theme variables:

Source signal:

Arguments:

See also:

Source signal:

Theme variables

Used by:

Used by:

Used by:

Tables

See also:

See also:

Module: `awful.permissions`