Module: `client`

A process window managed by AwesomeWM.

Clients are the name used by Awesome (and X11) to refer to a window.

A program can have multiple clients (e.g. for dialogs) or none at all (e.g. command line applications). Clients are usually grouped by classes. A class is the name used by X11 to help the window manager distinguish between windows and write rules for them. A client's behavior is also defined by its type and size_hints properties. See the xprop command line application to query properties for a client.

Client geometry

The client's :geometry() function returns a table with x, y, width and height. The area returned excludes the border width. All clients also have a shape_bounding and shape_clip used to "crop" the client's content. Finally, each clients can have titlebars (see awful.titlebar).

Some signal names are starting with a dot. These dots are artefacts from the documentation generation, you get the real signal name by removing the starting dot.

Accessing client objects can be done in multiple ways depending on the context. To get the currently focused client:

local c = client.focus
if c then
    -- do something
end

To get a list of all clients, use client:get:

for _, c in ipairs(client.get()) do
    -- do something
end

To execute a callback when a new client is added, use the manage signal:

client.connect_signal("request::manage", function(c)
    -- do something
end)

To be notified when a property of a client changed:

client.connect_signal("property::name", function(c)
    -- do something
end)

To be notified when a property of a specific client c changed:

c:connect_signal("property::name", function()
    -- do something
end)

To get all the clients for a screen use either screen.clients or screen.tiled_clients.

Core components relationship

Acquire other objects from a client
Class		Property
tag		c.tags
screen		c.screen
awful.key		c:keys()
awful.button		c:buttons()

Acquire a client from other objects
Class		Property
tag		t:clients()
screen		s.clients
screen		s.hidden_clients
screen		s.tiled_clients
mouse		mouse.current_client

Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object

Info:

Copyright: 2008-2009 Julien Danjou
Originally authored by: Julien Danjou <[email protected]>
(Full contributors list available on our github project)

Static module functions

client.instances () -> integer	Get the number of instances.
client.get (screen, stacked) -> table	Get all clients into a table.
client.disconnect_signal (name, func)	Disconnect from a signal.
client.emit_signal (name, ...)	Emit a signal.
client.connect_signal (name, func)	Connect to a signal.
awful.client.next (i, sel, stacked) -> client or nil	Get a client by its relative index to another client.
awful.client.swap.bydirection (dir, c, stacked)	Swap a client with another client in the given direction.
awful.client.swap.global_bydirection (dir, sel)	Swap a client with another client in the given direction.
awful.client.swap.byidx (i, c)	Swap a client by its relative index.
awful.client.cycle (clockwise, s, stacked)	Cycle through the clients to change the focus.
awful.client.restore (s) -> client	Restore (=unminimize) a random client.
awful.client.property.persist (prop, kind)	Set a client property to be persistent across restarts (via X properties).
awful.client.iterate (filter, start, s) -> function	Returns an iterator to cycle through clients.
awful.client.urgent.jumpto (merge)	Jump to the client that received the urgent hint first.

Object properties

window	integer	The X window id.	Read only
name	string	The client title.
skip_taskbar	boolean	True if the client does not want to be in taskbar.
type	string	The window type.	Read only
class	string	The client class.	Read only
instance	string	The client instance.	Read only
pid	integer	The client PID, if available.	Read only
role	string	The window role, if available.	Read only
machine	string	The machine the client is running on.	Read only
icon_name	string	The client name when iconified.	Read only
icon	image	The client icon as a surface.
icon_sizes	table	The available sizes of client icons.	Read only
screen	screen	Client screen.
hidden	boolean	Define if the client must be hidden (Never mapped, invisible in taskbar).
minimized	boolean	Define if the client must be iconified (Only visible in taskbar).
size_hints_honor	boolean	Honor size hints, e.g.
border_width	integer or nil	The client border width.
border_color	color or nil	The client border color.
urgent	boolean	Set to `true` when the client ask for attention.
content	raw_curface	A cairo surface for the client window content.	Read only
opacity	number	The client opacity.
ontop	boolean	The client is on top of every other windows.
above	boolean	The client is above normal windows.
below	boolean	The client is below normal windows.
fullscreen	boolean	The client is fullscreen or not.
maximized	boolean	The client is maximized (horizontally and vertically) or not.
maximized_horizontal	boolean	The client is maximized horizontally or not.
maximized_vertical	boolean	The client is maximized vertically or not.
transient_for	client or nil	The client the window is transient for.	Read only
group_window	integer	Window identification unique to a group of windows.	Read only
leader_window	integer	Identification unique to windows spawned by the same command.	Read only
size_hints	table or nil	A table with size hints of the client.	Read only
motif_wm_hints	table	The motif WM hints of the client.	Read only
sticky	boolean	Set the client sticky (Available on all tags).
modal	boolean	Indicate if the client is modal.
focusable	boolean	True if the client can receive the input focus.
shape_bounding	image	The client's bounding shape as set by awesome as a (native) cairo surface.
shape_clip	image	The client's clip shape as set by awesome as a (native) cairo surface.
shape_input	image	The client's input shape as set by awesome as a (native) cairo surface.
client_shape_bounding	image	The client's bounding shape as set by the program as a (native) cairo surface.	Read only
client_shape_clip	image	The client's clip shape as set by the program as a (native) cairo surface.	Read only
startup_id	string	The FreeDesktop StartId.
valid	boolean	If the client that this object refers to is still managed by awesome.	Read only
first_tag	tag or nil	The first tag of the client.	Read only
buttons	table	Get or set mouse buttons bindings for a client.
keys	table	Get or set keys bindings for a client.
marked	boolean	If a client is marked or not.
is_fixed	boolean	Return if a client has a fixed size or not.	Read only
immobilized_horizontal	boolean	Is the client immobilized horizontally?	Read only
immobilized_vertical	boolean	Is the client immobilized vertically?	Read only
floating	boolean	The client floating state.
x	integer	The x coordinates.
y	integer	The y coordinates.
width	integer	The width of the client.
height	integer	The height of the client.
dockable	boolean	If the client is dockable.
requests_no_titlebar	boolean	If the client requests not to be decorated with a titlebar.
shape	shape	Set the client shape.
active	boolean	Return true if the client is active (has focus).	Read only

Object methods

:struts (struts) -> table	Return client struts (reserved space at the edge of the screen).
:isvisible () -> boolean	Check if a client is visible on its screen.
:kill ()	Kill a client.
:swap (c)	Swap a client with another one in global client list.
:tags (tags_table) -> table	Access or set the client tags.
:raise ()	Raise a client on top of others which are on the same layer.
:lower ()	Lower a client on bottom of others which are on the same layer.
:unmanage ()	Stop managing a client.
:geometry (geo) -> table	Return or set client geometry.
:apply_size_hints (width, height) -> (integer, integer)	Apply size hints to a size.
:get_icon (index) -> surface	Get the client's n-th icon.
:jump_to (merge)	Jump to the given client.
:append_keybinding (key)	Append a keybinding.
:remove_keybinding (key)	Remove a keybinding.
:append_mousebinding (button)	Append a mousebinding.
:remove_mousebinding (button)	Remove a mousebinding.
:to_primary_section ()	Move the client to the most significant layout position.
:to_secondary_section ()	Move the client to the least significant layout position.
:relative_move (x, y, w, h)	Move/resize a client relative to current coordinates.
:move_to_tag (target)	Move a client to a tag.
:toggle_tag (target)	Toggle a tag on a client.
:move_to_screen (s)	Move a client to a screen.
:to_selected_tags ()	Find suitable tags for newly created clients.
:get_transient_for_matching (matcher) -> client or nil	Get a matching transient_for client (if any).
:is_transient_for (c2) -> client or nil	Is a client transient for another one?
:activate {[args]}	Activate (focus) a client.
:grant (permission, context)	Grant a permission for a client.
:deny (permission, context)	Deny a permission for a client.
:emit_signal (name, ...)	Emit a signal.	Inherited from gears.object
:connect_signal (name, func)	Connect to a signal.	Inherited from gears.object
:weak_connect_signal (name, func)	Connect to a signal weakly.	Inherited from gears.object

Signals

scanning	Emitted when AwesomeWM is about to scan for existing clients.
scanned	Emitted when AwesomeWM is done scanning for clients.
focus	Emitted when a client gains focus.
list	Emitted before request::manage, after request::unmanage, and when clients swap.
swapped	Emitted when 2 clients are swapped
request::manage	Emitted when a new client appears and gets managed by Awesome.
request::unmanage	Emitted when a client is going away.
button::press	Emitted when a mouse button is pressed in a client.
button::release	Emitted when a mouse button is released in a client.
mouse::enter	Emitted when the mouse enters a client.
mouse::leave	Emitted when the mouse leaves a client.
mouse::move	Emitted when the mouse moves within a client.
request::activate	Emitted when a client should get activated (focused and/or raised).
request::autoactivate	Emitted when an event could lead to the client being activated.
request::geometry	Emitted when something request a client's geometry to be modified.
request::tag	Emitted when a client requests to be moved to a tag or needs a new tag.
request::urgent	Emitted when any client's urgent property changes.
request::default_mousebindings	Emitted once to request default client mousebindings during the initial startup sequence.
request::default_keybindings	Emitted once to request default client keybindings during the initial startup sequence.
tagged	Emitted when a client gets tagged.
unfocus	Emitted when a client gets unfocused.
untagged	Emitted when a client gets untagged.
raised	Emitted when the client is raised within its layer.
lowered	Emitted when the client is lowered within its layer.
property::floating_geometry	The last geometry when client was floating.
request::titlebars	Emitted when a client need to get a titlebar.
request::border	Emitted when the border client might need to be update.

Deprecated signals

manage	Use request::manage.	Deprecated
unmanage	Use request::unmanage.	Deprecated
marked	The client marked signal.	Deprecated
unmarked	The client unmarked signal.	Deprecated

Theme variables

beautiful.border_color_marked	color	The border color when the client is marked.
beautiful.border_color_floating	color	The fallback border color when the client is floating.
beautiful.border_color_maximized	color	The fallback border color when the client is maximized.
beautiful.border_color_fullscreen	color	The fallback border color when the client is fullscreen.
beautiful.border_color_active	color	The border color when the client is active.
beautiful.border_color_normal	color	The border color when the client is not active.
beautiful.border_color_urgent	color	The border color when the client has the urgent property set.
beautiful.border_color_new	color	The border color when the client is not active and new.
beautiful.border_color_floating_active	color	The border color when the (floating) client is active.
beautiful.border_color_floating_normal	color	The border color when the (floating) client is not active.
beautiful.border_color_floating_urgent	color	The border color when the (floating) client has the urgent property set.
beautiful.border_color_floating_new	color	The border color when the (floating) client is not active and new.
beautiful.border_color_maximized_active	color	The border color when the (maximized) client is active.
beautiful.border_color_maximized_normal	color	The border color when the (maximized) client is not active.
beautiful.border_color_maximized_urgent	color	The border color when the (maximized) client has the urgent property set.
beautiful.border_color_maximized_new	color	The border color when the (maximized) client is not active and new.
beautiful.border_color_fullscreen_active	color	The border color when the (fullscreen) client is active.
beautiful.border_color_fullscreen_normal	color	The border color when the (fullscreen) client is not active.
beautiful.border_color_fullscreen_urgent	color	The border color when the (fullscreen) client has the urgent property set.
beautiful.border_color_fullscreen_new	color	The border color when the (fullscreen) client is not active and new.
beautiful.border_width	integer	The fallback border width when nothing else is set.
beautiful.border_width_floating	integer	The fallback border width when the client is floating.
beautiful.border_width_maximized	integer	The fallback border width when the client is maximized.
beautiful.border_width_normal	integer	The client border width for the normal clients.
beautiful.border_width_active	integer	The client border width for the active client.
beautiful.border_width_urgent	integer	The client border width for the urgent clients.
beautiful.border_width_new	integer	The client border width for the new clients.
beautiful.border_width_floating_normal	integer	The client border width for the normal floating clients.
beautiful.border_width_floating_active	integer	The client border width for the active floating client.
beautiful.border_width_floating_urgent	integer	The client border width for the urgent floating clients.
beautiful.border_width_floating_new	integer	The client border width for the new floating clients.
beautiful.border_width_maximized_normal	integer	The client border width for the normal maximized clients.
beautiful.border_width_maximized_active	integer	The client border width for the active maximized client.
beautiful.border_width_maximized_urgent	integer	The client border width for the urgent maximized clients.
beautiful.border_width_maximized_new	integer	The client border width for the new maximized clients.
beautiful.border_width_fullscreen_normal	integer	The client border width for the normal fullscreen clients.
beautiful.border_width_fullscreen_active	integer	The client border width for the active fullscreen client.
beautiful.border_width_fullscreen_urgent	integer	The client border width for the urgent fullscreen clients.
beautiful.border_width_fullscreen_new	integer	The client border width for the new fullscreen clients.
beautiful.border_width_fullscreen	integer	The client border width for the fullscreen clients.
beautiful.opacity_normal	number	The client opacity for the normal clients.
beautiful.opacity_active	number	The client opacity for the active client.
beautiful.opacity_urgent	number	The client opacity for the urgent clients.
beautiful.opacity_new	number	The client opacity for the new clients.
beautiful.opacity_floating_normal	number	The client opacity for the normal floating clients.
beautiful.opacity_floating_active	number	The client opacity for the active floating client.
beautiful.opacity_floating_urgent	number	The client opacity for the urgent floating clients.
beautiful.opacity_floating_new	number	The client opacity for the new floating clients.
beautiful.opacity_floating	number	The client opacity for the floating clients.
beautiful.opacity_maximized_normal	number	The client opacity for the normal maximized clients.
beautiful.opacity_maximized_active	number	The client opacity for the active maximized client.
beautiful.opacity_maximized_urgent	number	The client opacity for the urgent maximized clients.
beautiful.opacity_maximized_new	number	The client opacity for the new maximized clients.
beautiful.opacity_maximized	number	The client opacity for the maximized clients.
beautiful.opacity_fullscreen_normal	number	The client opacity for the normal fullscreen clients.
beautiful.opacity_fullscreen_active	number	The client opacity for the active fullscreen client.
beautiful.opacity_fullscreen_urgent	number	The client opacity for the urgent fullscreen clients.
beautiful.opacity_fullscreen_new	number	The client opacity for the new fullscreen clients.
beautiful.opacity_fullscreen	number	The client opacity for the fullscreen clients.

Deprecated functions

awful.client.jumpto (c, merge)	Jump to the given client.	Deprecated
awful.client.visible (s, stacked)	Get visible clients from a screen.	Deprecated
awful.client.tiled (s, stacked)	Get visible and tiled clients	Deprecated
awful.client.getmaster (s)	Get the master window.	Deprecated
awful.client.setmaster (c)	Set the client as master: put it at the beginning of other windows.	Deprecated
awful.client.setslave (c)	Set the client as slave: put it at the end of other windows.	Deprecated
awful.client.moveresize (x, y, w, h, c)	Move/resize a client relative to current coordinates.	Deprecated
awful.client.movetotag (target, c)	Move a client to a tag.	Deprecated
awful.client.toggletag (target, c)	Toggle a tag on a client.	Deprecated
awful.client.movetoscreen (c, s)	Move a client to a screen.	Deprecated
awful.client.mark (c)	Mark a client, and then call 'marked' hook.	Deprecated
awful.client.unmark (c)	Unmark a client and then call 'unmarked' hook.	Deprecated
awful.client.ismarked (c)	Check if a client is marked.	Deprecated
awful.client.togglemarked (c)	Toggle a client as marked.	Deprecated
awful.client.getmarked ()	Return the marked clients and empty the marked table.	Deprecated
awful.client.floating.set (c, s)	Set a client floating state, overriding auto-detection.	Deprecated
awful.client.isfixed (c)	Return if a client has a fixed size or not.	Deprecated
awful.client.floating.get (c)	Get a client floating state.	Deprecated
awful.client.floating.toggle (c)	Toggle the floating state of a client between 'auto' and 'true'.	Deprecated
awful.client.dockable.get (c)	Get a client's dockable state.	Deprecated
awful.client.dockable.set (c, value)	Set a client's dockable state, overriding auto-detection.	Deprecated
awful.client.property.get (c, prop)	Get a client property.	Deprecated
awful.client.property.set (c, prop, value)	Set a client property.	Deprecated
awful.client.run_or_raise (cmd, matcher, merge)	Switch to a client matching the given condition if running, else spawn it.	Deprecated
awful.client.get_transient_for_matching (c, matcher)	Get a matching transient_for client (if any).	Deprecated
awful.client.is_transient_for (c, c2)	Is a client transient for another one?	Deprecated

Layout related functions

awful.client.idx	Calculate a client's column number, index in that column, and number of visible clients in this column.
awful.client.setwfact	Define how tall a client should be in the tile layout.
awful.client.incwfact	Change window factor of a client.

Extra properties available in the rules

placement	N/A	The client default placement on the screen.
honor_padding	boolean	When applying the placement, honor the screen padding.
honor_workarea	boolean	When applying the placement, honor the screen work area.
tag	tag	The client default tag.
tags	table	The client default tags.
new_tag	table or string or boolean	Create a new tag for this client.
switch_to_tags	boolean	Unselect the current tags and select this client tags.
focus	boolean	Define if the client should grab focus by default.
titlebars_enabled	boolean	Should this client have a titlebar by default.
callback	N/A	A function to call when this client is ready.

Tables

awful.client.object

Client class.

Fields

client.focus

client

The focused client or nil (in case there is none).

lib.awful.client.focus Functions

awful.client.focus.history.delete (c)	Remove a client from the focus history
awful.client.focus.byidx (i, c)	Focus a client by its relative index.
awful.client.focus.filter (c)	Filter out window that we do not want handled by focus.
awful.client.focus.history.add (c)	Update client focus history.
awful.client.focus.history.get (s, idx, filter)	Get the latest focused client for a screen in history.
awful.client.focus.history.previous ()	Focus the previous client in history.
awful.client.focus.bydirection (dir, c, stacked)	Focus a client by the given direction.
awful.client.focus.global_bydirection (dir, c, stacked)	Focus a client by the given direction.
awful.client.focus.history.is_enabled ()	Is history tracking enabled?
awful.client.focus.history.enable_tracking ()	Enable history tracking.
awful.client.focus.history.disable_tracking ()	Disable history tracking.

Static module functions

🔗 client.instances () -> integer

Get the number of instances.

Returns:

integer

🔗 client.get (screen, stacked) -> table

Get all clients into a table.

Parameters:

Name		Type(s)	Description
screen	Optional	integer or screen	A screen number to filter clients on.
stacked	Optional	boolean	Return clients in stacking order? (ordered from top to bottom).

Returns:

table

Usage:

for _, c in ipairs(client.get()) do
    -- do something
end

🔗 client.disconnect_signal (name, func)

Disconnect from a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback that should be disconnected.

🔗 client.emit_signal (name, ...)

Emit a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
...			Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 client.connect_signal (name, func)

Connect to a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback to call when the signal is emitted.

🔗 awful.client.next (i, sel, stacked) -> client or nil

Get a client by its relative index to another client. If no client is passed, the focused client will be used.

Parameters:

Name		Type(s)	Description	Default value
i		int	The index. Use `1` to get the next, `-1` to get the previous.	Not applicable
sel	Optional	client	The client.	`client.focus`
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Returns:

client or nil

Usage:

-- focus the next window in the index
awful.client.next(1)
-- focus the previous
awful.client.next(-1)

🔗 awful.client.swap.bydirection (dir, c, stacked)

Swap a client with another client in the given direction.

This will not cross the screen boundary. If you want this behavior, use awful.client.swap.global_bydirection.

-- It will go up in the same column.
awful.client.swap.bydirection("up", client.focus)

-- Nothing happens because it cannot change screen.
awful.client.swap.bydirection("right", client.focus)

-- Moves to the first column.
awful.client.swap.bydirection("left", client.focus)

Parameters:

Name		Type(s)	Description	Default value
dir		string	The direction, can be either "up", "down", "left" or "right".	Not applicable
c	Optional	client	The client.	`"focused"`
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Parameters:

Name		Type(s)	Description	Default value
dir		string	The direction, can be either "up", "down", "left" or "right".	Not applicable
sel	Optional	client	The client.	`client.focus`

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.swap.global_bydirection	granted	When a client could be activated because awful.client.swap.global_bydirection was called.

🔗 awful.client.swap.byidx (i, c)

Swap a client by its relative index.

Usage example output:

c1:1, c2:2, c3:3, c4:4,
Call swap.byidx
c4:1, c2:2, c3:3, c1:4,
Call swap.byidx
c4:1, c1:2, c3:3, c2:4,

Usage example:

-- Print at which index each client is now at.
local function print_indices()
    local output = ""

    for idx, c in ipairs(client.get()) do
         output = output .. c.name .. ":" .. idx .. ", "
    end

    print(output)
end

print_indices()

print("Call swap.byidx")
awful.client.swap.byidx(3, client.get()[1])
print_indices()

print("Call swap.byidx")
awful.client.swap.byidx(2, client.get()[4])
print_indices()

Parameters:

Name		Type(s)	Description	Default value
i		integer	The index. Use `1` to get the next, `-1` to get the previous.	Not applicable
c	Optional	client	The client, otherwise focused one is used.	`client.focus`

Parameters:

Name		Type(s)	Description	Default value
clockwise	Optional	boolean	True to cycle clients clockwise.	`false`
s	Optional	screen	The screen where to cycle clients.	`awful.screen.focused()`
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Parameters:

Name		Type(s)	Description
s		screen	The screen to use.

Returns:

client

🔗 awful.client.property.persist (prop, kind)

Set a client property to be persistent across restarts (via X properties).

Parameters:

Name		Type(s)	Description
prop		string	The property name.
kind		string	The type (used for register_xproperty). One of "string", "number" or "boolean".

🔗 awful.client.iterate (filter, start, s) -> function

Returns an iterator to cycle through clients.

Starting from the client in focus or the given index, all clients that match a given criteria.

Parameters:

Name		Type(s)	Description	Default value
filter		function	A function that returns true to indicate a positive match.	Not applicable
start		integer	What index to start iterating from. Defaults to using the index of the currently focused client.	Not applicable
s	Optional	screen	Which screen to use. nil means all screens.	`nil`

Returns:

function

for

Usage:

-- un-minimize all urxvt instances
local urxvt = function (c)
  return ruled.client.match(c, {class = "URxvt"})
end

for c in awful.client.iterate(urxvt) do
  c.minimized = false
end

🔗 awful.client.urgent.jumpto (merge)

Jump to the client that received the urgent hint first.

awful.client.urgent.jumpto(false)

Parameters:

Name		Type(s)	Description
merge		bool or function	If true then merge tags (select the client's first tag additionally) when the client is not visible. If it is a function, it will be called with the client as argument.

Object properties

🔗 window integer · 1 signal · read only

The X window id.

This is rarely useful, but some DBus protocols will have this ID in their API, so it can be useful when writing AwesomeWM bindings for them.

Constraints:

Default value	: This is generated by X11.
Negative allowed	: false

Click to display more

Emit signals:

property::window When the window value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 name string · 1 signal

The client title.

This is the text which will be shown in awful.widget.tasklist and awful.titlebar.widget.titlewidget.

Constraints:

Default value

: This is provided by the application.

Emit signals:

property::name When the name value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 skip_taskbar boolean · 1 signal

True if the client does not want to be in taskbar.

Some clients, like docked bars or some sticky clients such as wallpaper sensors like Conky have no value in the awful.widget.tasklist and should not be shown there.

The default value of this property reflects the value of the _NET_WM_STATE_SKIP_TASKBAR X11 protocol xproperty. Clients can modify this state through this property.

c1.skip_taskbar = false
c2.skip_taskbar = true
c3.skip_taskbar = false

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::skip_taskbar When the skip_taskbar value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 type string · 1 signal · read only

The window type.

This is useful in, among other places, the ruled.client rules to apply different properties depending on the client types. It is also used throughout the API to alter the client (and wibox) behavior depending on the type. For example, clients with the dock type are placed on the side of the screen while other like combo are totally ignored and never considered clients in the first place.

Valid types are:

Name	Description
desktop	The root client, it cannot be moved or resized.
dock	A client attached to the side of the screen.
splash	A client, usually without titlebar shown when an application starts.
dialog	A dialog, see transient_for.
menu	A context menu.
toolbar	A floating toolbar.
utility
dropdown_menu	A context menu attached to a parent position.
popup_menu	A context menu.
notification	A notification popup.
combo	A combobox list menu.
dnd	A drag and drop indicator.
normal	A normal application main window.

More information can be found here

Constraints:

Default value

: This is provided by the application.

Emit signals:

property::type When the type value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 class string · 1 signal · read only

The client class.

A class usually maps to the application name. It is useful in, among other places, the rules to apply different properties to different clients. It is also useful, along with instance, to implement "windows counter" used in many popular docks and Alt-Tab like popups.

To get a client class from the command line, use the command:

xprop WM_CLASS

The class will be the second string.

This should never change after the client is created, but some buggy application like the Spotify desktop client are known to violate the specification and do it anyway. There is a signal for this property, but it should hopefully never be useful. If your applications change their classes, please report a bug to them and point to ICCCM §4.1.2.5. It tends to break ruled.client and other AwesomeWM APIs.

Constraints:

Default value

: This is provided by the application.

Emit signals:

property::class When the class value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 instance string · 1 signal · read only

The client instance.

The instance is a subtype of the class. Each class can have multiple instances. This is useful in the ruled.client rules to filter clients and apply different properties to them.

To get a client instance from the command line, use the command:

 xprop WM_CLASS

The instance will be the first string.

This should never change after the client is created. There is a signal for * this property, but it should hopefully never be useful. If your applications change their classes, please report a bug to them and point to ICCCM §4.1.2.5. It tends to break ruled.client and other AwesomeWM APIs.

Constraints:

Default value

: This is provided by the application.

Emit signals:

property::instance When the instance value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 pid integer · 1 signal · read only

The client PID, if available.

This will never change.

Constraints:

Default value	: This is randomly assigned by the kernel.
Negative allowed	: false

Click to display more

Emit signals:

property::pid When the pid value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 role string · 1 signal · read only

The window role, if available.

Constraints:

Default value

: This is provided by the application.

Emit signals:

property::role When the role value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 machine string · 1 signal · read only

The machine the client is running on.

X11 windows can "live" in one computer but be shown in another one. This is called "network transparency" and is either used directly by allowing remote windows using the xhosts command or using proxies such as ssh -X or ssh -Y.

According to EWMH, this property contains the value returned by gethostname() on the computer that the client is running on.

Constraints:

Default value

: This is the hostname unless the client is from an SSH session or using the rarely used direct X11 network socket.

Click to display more

Emit signals:

property::machine When the machine value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 icon_name string · 1 signal · read only

The client name when iconified.

Constraints:

Default value

: This is provided by the application.

Click to display more

Emit signals:

property::icon_name When the icon_name value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 icon image · 1 signal

The client icon as a surface.

This property holds the client icon closest to the size configured via awesome.set_preferred_icon_size.

It is not a path or a "real" file. Rather, it is already a bitmap surface.

Typically you would want to use awful.widget.clienticon to get this as a widget.

Working with icons is tricky because their surfaces do not use reference counting correctly. If gears.surface(c.icon) is called multiple time on the same icon, it will cause a double-free error and Awesome will crash. To get a copy of the icon, you can use:

local s = gears.surface(c.icon)
local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height())
local cr  = cairo.Context(img)
cr:set_source_surface(s, 0, 0)
cr:paint()

(Note that awesome.set_preferred_icon_size defaults to 0 if it wasn't set. It means that, by default, the preferred icon provided will be the smallest available)

Constraints:

Default value	: This is provided by the application.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Usage:

local ib = wibox.widget.imagebox(c.icon)

Click to display more

Emit signals:

property::icon When the icon value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 icon_sizes table · 1 signal · read only

The available sizes of client icons. This is a table where each entry contains the width and height of an icon.

Example:

{
  { 24, 24 },
  { 32, 32 },
  { 64, 64 },
}

Constraints:

Default value	: This is provided by the application.
Table content:	: A list of tables. Each table has the following rows:
`1` (integer)	: The width value.
`2` (integer)	: The height value.

Emit signals:

property::icon_sizes When the icon_sizes value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 screen screen · 1 signal

Client screen.

The screen corresponds to the top-left corner of the window.

Please note that clients can only be on one screen at once. X11 does not natively allow clients to be in multiple locations at once. Changing the screen directly will affect the tags and may cause several other changes to the state in order to ensure that a client's position and its screen are consistent.

  -- Move the mouse to screen 3
  mouse.coords {x = 1800, y = 100 }

  -- Spawn a client on screen #3
  awful.spawn("firefox")

  client.get()[1].screen = screen[2]

Constraints:

Default value	: This usually correspond to where the top-left (or other gravities) is placed. Then it is mapped to the screen `geometry`.
Type description:
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.

Emit signals:

property::screen When the screen value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 hidden boolean · 1 signal

Define if the client must be hidden (Never mapped, invisible in taskbar).

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::hidden When the hidden value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 minimized boolean · 1 signal

Define if the client must be iconified (Only visible in taskbar).

Minimized clients are still part of tags and screens, but they are not displayed. You can unminimize using c.minimized = false, but if you also want to set the focus, it is better to use:

c:activate { context = "unminimized", raise = true }

  for _ = 1, 3 do
      awful.spawn("")
  end

 client.get()[1].minimized = true

 -- That's the best way to unminimize if you also want to set the focus.
 client.get()[1]:activate {
     context = "unminimize",
     raise   = true,
 }

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::minimized When the minimized value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 size_hints_honor boolean · 1 signal

Honor size hints, e.g. respect size ratio.

For example, a terminal such as xterm require the client size to be a multiple of the character size. Honoring size hints will cause the terminal window to have a small gap at the bottom.

This is enabled by default. To disable it by default, see ruled.client.

Constraints:

Default value	: `true`
Valid values	: `true` or `false`.

Emit signals:

property::size_hints_honor When the size_hints_honor value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 border_width integer or nil · 1 signal · 21 theme variables

The client border width.

When manually set (for example, in ruled.client rules), this value will be static. Otherwise, it is controlled by many beautiful variables.

Be careful, the borders are around the geometry, not part of it. If you want more fancy border, use the awful.titlebar API to create titlebars on each side of the client.

c1.border_width = 0
c2.border_width = 2
c3.border_width = 10

Constraints:

Default value	: `nil`
Type description:
nil	: Let AwesomeWM manage it based on the client state.
Unit	: pixel
Negative allowed	: false

Emit signals:

property::border_width When the border_width value changes.

self client The object which changed (useful when connecting many object to the same callback).

Consumed theme variables:

Theme variable	Usage
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.fullscreen_hide_border`	Hide the border on fullscreen clients.
`beautiful.maximized_hide_border`	Hide the border on maximized clients.

🔗 border_color color or nil · 1 signal · 20 theme variables

The client border color.

  c.border_color = "#ff00ff"

Note that setting this directly will override and disable all related theme variables.

Setting a transparent color (e.g. to implement dynamic borders without size changes) is supported, but requires the color to be set to #00000000 specifically. Other RGB colors with an alpha of 0 won't work.

Constraints:

Default value	: `nil`
Type description:
nil	: Let AwesomeWM manage it based on the client state.
string	: An hexadecimal color code, such as `"#ff0000"` for red.
string	: A color name, such as `"red"`.
table	: A gradient table.
cairo.pattern	: Any valid Cairo pattern.
cairo.pattern	: A texture build from an image by gears.color.create_png_pattern

Emit signals:

property::border_color When the border_color value changes.

self client The object which changed (useful when connecting many object to the same callback).

Consumed theme variables:

Theme variable	Usage
beautiful.border_color_marked	The fallback color when the client is marked.
beautiful.border_color_active	The fallback color when the client is active (focused).
beautiful.border_color_normal	The fallback color when the client isn't active/floating/new/urgent/maximized/floating/fullscreen.
beautiful.border_color_new	The fallback color when the client is new.
beautiful.border_color_urgent	The fallback color when the client is urgent.
beautiful.border_color_floating	The fallback color when the client is floating and the other colors are not set.
beautiful.border_color_floating_active	The color when the client is floating and is active (focused).
beautiful.border_color_floating_normal	The color when the client is floating and not new/urgent/active.
beautiful.border_color_floating_new
beautiful.border_color_floating_urgent	The color when the client is floating and 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	The color when the client is urbent and maximized.
beautiful.border_color_fullscreen
beautiful.border_color_fullscreen_active
beautiful.border_color_fullscreen_normal
beautiful.border_color_fullscreen_new
beautiful.border_color_fullscreen_urgent	The color when the client is fullscreen and urgent.

🔗 urgent boolean · 1 signal · 13 theme variables · 3 permissions

Set to true when the client ask for attention.

The urgent state is the visual equivalent of the "bell" noise from old computer. It is set by the client when their state changed and they need attention. For example, a chat client will set it when a new message arrive. Some terminals, like rxvt-unicode, will also set it when calling the bell command.

There is many ways an urgent client can become for visible:

Highlight in the awful.widget.taglist and awful.widget.tasklist
Highlight in the awful.titlebar
Highlight of the client border color (or width).
Accessible using Mod4+u in the default config.
Emit the property::urgent signal.

-- Affects mostly the taglist and tasklist..
beautiful.fg_urgent = "#ffffff"
beautiful.bg_urgent = "#ff0000"

-- Set the client border to be orange and large.
beautiful.border_color_urgent = "#ffaa00"
beautiful.border_width_urgent = 6

-- Set the titlebar green.
beautiful.titlebar_bg_urgent = "#00ff00"
beautiful.titlebar_fg_urgent = "#000000"

-- This client is in the current tag.
c2.urgent = true

-- This client is in a deselected tag.
c4.urgent = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::urgent When the urgent value changes.

self client The object which changed (useful when connecting many object to the same callback).

Consumed theme variables:

Theme variable	Usage
beautiful.border_color_urgent	The fallback color when the client is urgent.
beautiful.border_color_floating_urgent	The color when the client is floating and urgent.
beautiful.border_color_maximized_urgent	The color when the client is urbent and maximized.
beautiful.border_color_fullscreen_urgent	The color when the client is fullscreen and urgent.
beautiful.border_width_urgent	The fallback border width when the client is urgent.
beautiful.border_width_floating_urgent	The border width when the client is floating and urgent.
beautiful.border_width_maximized_urgent	The border width when the client is maximized and urgent.
beautiful.border_width_fullscreen_urgent	The border width when the client is fullscreen and urgent.
`beautiful.titlebar_fg_urgent`
`beautiful.titlebar_bg_urgent`
`beautiful.titlebar_bgimage_urgent`
beautiful.fg_urgent
beautiful.bg_urgent

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	border	active	granted	When a client becomes active and is no longer urgent.
client	border	inactive	granted	When a client stop being active and is no longer urgent.
client	border	urgent	granted	When a client stop becomes urgent.

🔗 content raw_curface · read only

A cairo surface for the client window content.

To get the screenshot, use:

gears.surface(c.content)

To save it, use:

gears.surface(c.content):write_to_png(path)

Please note that this only creates a new cairo surface referring to the client's content. This means that changes to the client's content may or may not become visible in the returned surface. If you want to take a screenshot, a copy of the surface's content needs to be taken. Note that the content of parts of a window that are currently not visible are undefined.

The only way to get an animated client screenshot widget is to poll this property multiple time per seconds. This is obviously a bad idea.

This property has no signals when the content changes.

Constraints:

Default value

: This is a live surface. Always use gears.surface to take a snapshot.

Constraints:

Default value	: `1.0`
Minimum value	: 0.0 Transparent.
Maximum value	: 1.0 Opaque.

Emit signals:

property::opacity When the opacity value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 ontop boolean · 1 signal

The client is on top of every other windows.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::ontop When the ontop value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 above boolean · 1 signal

The client is above normal windows.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::above When the above value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 below boolean · 1 signal

The client is below normal windows.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::below When the below value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 fullscreen boolean · 1 signal · 1 permission

The client is fullscreen or not.

  screen[1].clients[1].maximized            = true
  screen[2].clients[1].maximized_vertical   = true
  screen[3].clients[1].maximized_horizontal = true
  screen[4].clients[1].fullscreen           = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::fullscreen When the fullscreen value changes.

self client The object which changed (useful when connecting many object to the same callback).

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	fullscreen	granted	When the client must be resized because it became (or stop being) fullscreen.

🔗 maximized boolean · 1 signal · 1 permission

The client is maximized (horizontally and vertically) or not.

  screen[1].clients[1].maximized            = true
  screen[2].clients[1].maximized_vertical   = true
  screen[3].clients[1].maximized_horizontal = true
  screen[4].clients[1].fullscreen           = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::maximized When the maximized value changes.

self client The object which changed (useful when connecting many object to the same callback).

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	maximized	granted	When the client must be resized because it became (or stop being) maximized.

🔗 maximized_horizontal boolean · 1 signal · 1 permission

The client is maximized horizontally or not.

  screen[1].clients[1].maximized            = true
  screen[2].clients[1].maximized_vertical   = true
  screen[3].clients[1].maximized_horizontal = true
  screen[4].clients[1].fullscreen           = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::maximized_horizontal When the maximized_horizontal value changes.

self client The object which changed (useful when connecting many object to the same callback).

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	maximized_horizontal	granted	When the client must be resized because it became (or stop being) maximized horizontally.

🔗 maximized_vertical boolean · 1 signal · 1 permission

The client is maximized vertically or not.

  screen[1].clients[1].maximized            = true
  screen[2].clients[1].maximized_vertical   = true
  screen[3].clients[1].maximized_horizontal = true
  screen[4].clients[1].fullscreen           = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::maximized_vertical When the maximized_vertical value changes.

self client The object which changed (useful when connecting many object to the same callback).

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	maximized_vertical	granted	When the client must be resized because it became (or stop being) maximized vertically.

🔗 transient_for client or nil · 1 signal · read only

The client the window is transient for.

A transient window is a client that "belongs" to another client. If the client is also modal, then the parent client cannot be focused while the child client exists. This is common for "Save as" dialogs or other dialogs where it is not possible to modify the content of the "parent" client while the dialog is open.

However, modal is not a requirement for using the transient_for concept. "Tools" such as popup palette in canvas-and-palettes applications can belong to each other without being modal.

Constraints:

Default value : nil

Emit signals:

property::transient_for When the transient_for value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 group_window integer · 1 signal · read only

Window identification unique to a group of windows.

This is the ID of the group window, not a client object. The group window is most likely not a visible client, but only an invisible and internal window.

Constraints:

Default value	: This is auto-generated by X11.
Negative allowed	: false

Emit signals:

property::group_window When the group_window value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 leader_window integer · 1 signal · read only

Identification unique to windows spawned by the same command.

This is the ID of the group window, not a client object.

Constraints:

Default value	: This is auto-generated by X11.
Negative allowed	: false

Emit signals:

property::leader_window When the leader_window value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 size_hints table or nil · 1 signal · read only

A table with size hints of the client.

For details on the meaning of the fields, refer to ICCCM § 4.1.2.3 WM_NORMAL_HINTS.

Please note that most fields are optional and may or may not be set.

When the client is tiled, the size_hints usually get in the way and cause the layouts to behave incorrectly. To mitigate this, it is often advised to set size_hints_honor to false in the ruled.client rules.

Constraints:

Default value	: `nil`
Table keys:
user_position (table\|nil)	: A table with `x` and `y` keys. It contains the preferred position of the client. This is set when the position has been modified by the user. See `program_position`.
program_position (table\|nil)	: A table with `x` and `y` keys. It contains the preferred position of the client. This is set when the application itself requests a specific position. See `user_position`.
user_size (table\|nil)	: A table with `width` and `height`. This contains the client preferred size when it has previously been set by the user. See `program_size` for the equivalent when the applications itself wants to specify its preferred size.
program_size (table\|nil)	: A table with `width` and `height`. This contains the client preferred size as specified by the application.
max_width (integer\|nil)	: The maximum width (in pixels).
max_height (integer\|nil)	: The maximum height (in pixels).
min_width (integer\|nil)	: The minimum width (in pixels).
min_height (integer\|nil)	: The minimum height (in pixels).
width_inc (integer\|nil)	: The number of pixels by which the client width may be increased or decreased. For example, for terminals, the size has to be proportional with the monospace font size.
height_inc (integer\|nil)	: The number of pixels by which the client height may be increased or decreased. For example, for terminals, the size has to be proportional with the monospace font size.
win_gravity (string\|nil)	: The client `gravity` defines the corder from which the size is computed. For most clients, it is `north_west`, which corresponds to the top-left of the window. This will affect how the client is resized and other size related operations.
min_aspect_num (integer\|nil)
min_aspect_den (integer\|nil)
max_aspect_num (integer\|nil)
max_aspect_den (integer\|nil)
base_width (integer\|nil)
base_height (integer\|nil)

Emit signals:

property::size_hints When the size_hints value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 motif_wm_hints table · 1 signal · read only

The motif WM hints of the client.

This is nil if the client has no motif hints. Otherwise, this is a table that contains the present properties. Note that awesome provides these properties as-is and does not interpret them for you. For example, if the function table only has "resize" set to true, this means that the window requests to be only resizable, but asks for the other functions not to be able. If however both "resize" and "all" are set, this means that all but the resize function should be enabled.

Constraints:

Default value	: `{}`
Table keys:
functions.all (boolean)
functions.resize (boolean)
functions.move (boolean)
functions.minimize (boolean)
functions.maximize (boolean)
functions.close (boolean)
decorations.all (boolean)
decorations.border (boolean)
decorations.resizeh (boolean)
decorations.title (boolean)
decorations.menu (boolean)
decorations.minimize (boolean)
decorations.maximize (boolean)
input_mode (string)	: This is either `modeless`, `primary_application_modal`, `system_modal`, `full_application_modal` or `unknown`.
status.tearoff_window (boolean)

Click to display more

Emit signals:

property::motif_wm_hints When the motif_wm_hints value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 sticky boolean · 1 signal

Set the client sticky (Available on all tags).

Please note that AwesomeWM implements sticky clients per screens rather than globally like some other implementations.

  -- Add a client.
  awful.spawn("xterm")

  -- Set sticky = true
  screen[1].clients[1].sticky = true

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::sticky When the sticky value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 modal boolean · 1 signal

Indicate if the client is modal.

A transient window is a client that "belongs" to another client. If the client is also modal, then it always has to be on top of the other window and the parent client cannot be focused while the child client exists. This is common for "Save as" dialogs or other dialogs where is not possible to modify the content of the "parent" client while the dialog is open.

However, modal is not a requirement for using the transient_for concept. "Tools" such as popup palette in canvas-and-palettes applications can belong to each other without being modal.

Constraints:

Default value	: This is provided by the application.
Valid values	: `true` or `false`.

Emit signals:

property::modal When the modal value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 focusable boolean · 1 signal

True if the client can receive the input focus.

The client will not get focused even when the user click on it.

Constraints:

Default value	: `true`
Valid values	: `true` or `false`.

Emit signals:

property::focusable When the focusable value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 shape_bounding image · 1 signal

The client's bounding shape as set by awesome as a (native) cairo surface.

The bounding shape is the outer shape of the client. It is outside of the border.

Do not use this directly unless you want total control over the shape (such as shape with holes). Even then, it is usually recommended to use transparency in the titlebars and a compositing manager. For the vast majority of use cases, use the shape property.

Constraints:

Default value	: An A1 surface where all pixels are white.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::shape_bounding When the shape_bounding value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 shape_clip image · 1 signal

The client's clip shape as set by awesome as a (native) cairo surface.

The shape_clip is the shape of the client content. It is inside the border.

Constraints:

Default value	: An A1 surface where all pixels are white.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::shape_clip When the shape_clip value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 shape_input image · 1 signal

The client's input shape as set by awesome as a (native) cairo surface.

The input shape is the shape where mouse input will be passed to the client rather than propagated below it.

Constraints:

Default value	: An A1 surface where all pixels are white.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::shape_input When the shape_input value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 client_shape_bounding image · 1 signal · read only

The client's bounding shape as set by the program as a (native) cairo surface.

Constraints:

Default value	: An A1 surface where all pixels are white.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::client_shape_bounding When the client_shape_bounding value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 client_shape_clip image · 1 signal · read only

The client's clip shape as set by the program as a (native) cairo surface.

Constraints:

Default value	: An A1 surface where all pixels are white.
Type description:
string	: Interpreted as a path to an image file.
string	: A valid SVG content.
cairo	: A cairo image surface: Directly used as-is.
librsvg	: A librsvg handle object: Directly used as-is.
nil	: Unset the image.

Emit signals:

property::client_shape_clip When the client_shape_clip value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 startup_id string · 1 signal

The FreeDesktop StartId.

When a client is spawned (like using a terminal or awful.spawn), a startup notification identifier is created. When the client is created, this identifier remain the same. This allow to match a spawn event to an actual client.

This is used to display a different mouse cursor when the application is loading and also to attach some properties to the newly created client (like a tag or floating state).

Some applications, like xterm, don't support startup notification. While not perfect, the addition the following code to rc.lua will mitigate the issue. Please note that this code is Linux specific.

local blacklisted_snid = setmetatable({}, {__mode = "v" })

--- Make startup notification work for some clients like XTerm. This is ugly
-- but works often enough to be useful.
local function fix_startup_id(c)
    -- Prevent "broken" sub processes created by <code>c</code> to inherit its SNID
    if c.startup_id then
        blacklisted_snid[c.startup_id] = blacklisted_snid[c.startup_id] or c
        return
    end

    if not c.pid then return end

    -- Read the process environment variables
    local f = io.open("/proc/"..c.pid.."/environ", "rb")

    -- It will only work on Linux, that's already 99% of the userbase.
    if not f then return end

    local value = _VERSION <= "Lua 5.1" and "([^\z]*)\0" or "([^\0]*)\0"
    local snid = f:read("*all"):match("STARTUP_ID=" .. value)
    f:close()

    -- If there is already a client using this SNID, it means it's either a
    -- subprocess or another window for the same process. While it makes sense
    -- in some case to apply the same rules, it is not always the case, so
    -- better doing nothing rather than something stupid.
    if blacklisted_snid[snid] then return end

    c.startup_id = snid

    blacklisted_snid[snid] = c
end

ruled.client.add_rule_source(
    "snid", fix_startup_id, {}, {"awful.spawn", "ruled.client"}
)

Constraints:

Default value

: This is optionally provided by the application.

Emit signals:

property::startup_id When the startup_id value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 valid boolean · 1 signal · read only

If the client that this object refers to is still managed by awesome.

To avoid errors, use:

local is_valid = pcall(function() return c.valid end) and c.valid

Constraints:

Default value	: `true`
Valid values	: `true` or `false`.

Emit signals:

property::valid When the valid value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 first_tag tag or nil · 1 signal · read only

The first tag of the client.

Optimized form of c:tags()[1]. Not every workflow uses the ability to set multiple tags to a client. It is often enough to only get the first tag and ignore everything else.

Constraints:

Default value : nil

Emit signals:

property::first_tag When the first_tag value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 buttons table · 1 signal

Get or set mouse buttons bindings for a client.

Constraints:

Default value	: `{}`
Table content	: A list of awful.buttons objects.

Emit signals:

property::buttons When the buttons value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 keys table · 1 signal

Get or set keys bindings for a client.

Constraints:

Default value	: `{}`
Table content	: A list of awful.keys objects.

Emit signals:

property::keys When the keys value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 marked boolean · 3 signals

If a client is marked or not.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Click to display more

Emit signals:

marked (for legacy reasons, use property::marked)
unmarker (for legacy reasons, use property::marked)
property::marked

🔗 is_fixed boolean · 1 signal · read only

Return if a client has a fixed size or not.

Fixed size means it cannot be resized.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::is_fixed When the is_fixed value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 immobilized_horizontal boolean · read only

Is the client immobilized horizontally?

Does the client have a fixed horizontal position and width, i.e. is it fullscreen, maximized, or maximized_horizontal?

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Click to display more

Emit signals:

property::floating When the floating value changes.

self client The object which changed (useful when connecting many object to the same callback).

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	border	floating	granted	When a border update is required because the client focus status changed.
client	border	active	granted	When a client becomes active and is not floating.
client	border	inactive	granted	When a client stop being active and is not floating.

🔗 x integer · 3 signals

The x coordinates.

x (usually) originate from the top left. x does not include the outer client border, but rather where the content and/or titlebar starts.

client.focus.x = 100

Constraints:

Default value	: `c:geometry().x`
Negative allowed	: true

Emit signals:

property::geometry

geo table The geometry (with x, y, width, height).

property::x
property::position

🔗 y integer · 3 signals

The y coordinates.

y (usually) originate from the top left. y does not include the outer client border, but rather where the content and/or titlebar starts.

client.focus.y = 50

Constraints:

Default value	: `c:geometry().y`
Negative allowed	: true

Emit signals:

property::geometry

geo table The geometry (with x, y, width, height).

property::y
property::position

🔗 width integer · 3 signals

The width of the client.

client.focus.width = 100

Constraints:

Default value	: `c:geometry().width`
Minimum value	: 1

Emit signals:

property::geometry

geo table The geometry (with x, y, width, height).

property::width
property::size

🔗 height integer · 3 signals

The height of the client.

client.focus.height = 100

Constraints:

Default value	: `c:geometry().height`
Minimum value	: 1

Emit signals:

property::geometry

geo table The geometry (with x, y, width, height).

property::height
property::size

🔗 dockable boolean · 1 signal

If the client is dockable.

A dockable client is an application confined to the edge of the screen. The space it occupies is subtracted from the screen.workarea.

Clients with a type of "utility", "toolbar" or "dock" are dockable by default.

Constraints:

Default value	: `false`
Valid values	: `true` or `false`.

Emit signals:

property::dockable When the dockable value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 requests_no_titlebar boolean · 1 signal

If the client requests not to be decorated with a titlebar.

The motif wm hints allow a client to request not to be decorated by the WM in various ways. This property uses the motif MWM_DECOR_TITLE hint and interprets it as the client (not) wanting a titlebar.

Constraints:

Default value	: `false`
Valid values	: Whether the client requests not to get a titlebar.

Click to display more

Emit signals:

property::requests_no_titlebar When the requests_no_titlebar value changes.

self client The object which changed (useful when connecting many object to the same callback).

🔗 shape shape · 1 signal

Set the client shape.

 c1.shape = gears.shape.rectangle
 c2.shape = gears.shape.rounded_rect
 c3.shape = gears.shape.octogon

Constraints:

Default value	: `gears.shape.rectangle`
Type description:
gears.shape	: Like gears.shape.circle
function:	: This can be used for custom shapes or to set parameters of existing shapes.
Function prototype:
Parameters:
cr (cairo.context)	: A Cairo context
width (number)	: The area width.
height (number)	: The area height.
Return	: The function returns nothing.
Valid values	: A gears.shape compatible function.

Emit signals:

property::shape When the shape value changes.

self client The object which changed (useful when connecting many object to the same callback).
new_value shape The new value affected to the property.

🔗 active boolean · 2 permissions · read only

Return true if the client is active (has focus).

This property is READ ONLY. Use c:activate { context = "myreason" } to change the focus.

The reason for this is that directly setting the focus (which can also be done using client.focus = c) will bypass the focus stealing filters. This is easy at first, but as this gets called from more and more places, it quickly become unmanageable. This coding style is recommended for maintainable code:

-- Check if a client has focus:
if c.active then
    -- do something
end

-- Check if there is a active (focused) client:
if client.focus ~= nil then
    -- do something
end

-- Get the active (focused) client:
local c = client.focus

-- Set the focus:
c:activate {
    context       = "myreason",
    switch_to_tag = true,
}

-- Get notified when a client gets or loses the focus:
c:connect_signal("property::active", function(c, is_active)
    -- do something
end)

-- Get notified when any client gets or loses the focus:
client.connect_signal("property::active", function(c, is_active)
    -- do something
end)

-- Get notified when any client gets the focus:
client.connect_signal("focus", function(c)
    -- do something
end)

-- Get notified when any client loses the focus:
client.connect_signal("unfocus", function(c)
    -- do something
end)

Constraints:

Default value	: `true`
Valid values	: `true` or `false`.

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	border	active	granted	When a client becomes active.
client	border	inactive	granted	When a client stop being active.

Object methods

🔗 :struts (struts) -> table

Return client struts (reserved space at the edge of the screen).

The struts area is a table with a left, right, top and bottom keys to define how much space of the screen workarea this client should reserve for itself.

This corresponds to EWMH's _NET_WM_STRUT and _NET_WM_STRUT_PARTIAL.

In the example below, 2 object affect the workarea (using their struts):

The top wibar add a top=24
The bottom-left client add bottom=100, left=100

  -- Wibars and docked clients are the main users of the struts.
  local wibar = awful.wibar {
      position = "top",
      height   = 24, -- this will set the wibar own :struts() to top=24
  }
  -- This is the client in the bottom left.
  c.name     = "w. struts"
  c.floating = true

  c:geometry {
      x      = 0,
      y      = 380,
      height = 100,
      width  = 100,
  }

  c:struts {
      left   = 100,
      bottom = 100
  }

Parameters:

Name		Type(s)	Description	Default value
struts		table	A table with new strut values, or none.	Not applicable
left	Optional	integer		`0`
right	Optional	integer		`0`
top	Optional	integer		`0`
bottom	Optional	integer		`0`

Returns:

table

Returns:

boolean

🔗 :kill ()

Kill a client.

This method can be used to close (kill) a client using the X11 protocol. To use the POSIX way to kill a process, use awesome.kill (using the client pid property).

  -- Spawn a client on screen #3
  for i=1, 5 do
      awful.spawn("Client #"..i)
  end

  client.get()[5]:activate {}

  local c4, c5 =  client.get()[4], client.get()[5]

  -- Kill the clients.
  c4:kill()
  c5:kill()

Parameters:

Name		Type(s)	Description
c		client	A client to swap with.

Usage:

-- Spawn 5 clients.
for i=1, 5 do
    awful.spawn("Client #"..i)
end

client.get()[2]:activate {}

client.get()[2]:swap(client.get()[4])

Click to display more

Emit signals:

swapped

other client The other client.
is_origin boolean true when :swap() was called on self rather than the other client. false when :swap() was called on the other client.

list

🔗 :tags (tags_table) -> table · 1 signal

Access or set the client tags.

Use the first_tag field to access the first tag of a client directly.

Usage example output:

 Tag:   2   two
 Tag:   3   three

Usage example:

 for tag_idx = 1, 3 do
     for _ = 1, 3 do
         awful.spawn("", {tags = {screen[1].tags[tag_idx]}})
     end
 end

 client.get()[1]:tags {
     screen[1].tags[2],
     screen[1].tags[3]
 }

 -- It also works to get the tags.
 for _, t in ipairs(client.get()[1]:tags()) do
      print("Tag:", t.index, t.name)
 end

Parameters:

Name		Type(s)	Description
tags_table		table	A table with tags to set, or `nil` to get the current tags.

Returns:

table

Emit signals:

property::tags

🔗 :raise () · 1 signal

Raise a client on top of others which are on the same layer.

Emit signals:

raised

🔗 :lower () · 1 signal

Lower a client on bottom of others which are on the same layer.

Emit signals:

lowered

🔗 :unmanage ()

Stop managing a client.

🔗 :geometry (geo) -> table

Return or set client geometry.

Usage example output:

 Client geometry:   200 200 300 240

Usage example:

  awful.spawn("")

  client.get()[1].floating = true

  client.get()[1]:geometry {
      x      = 200,
      y      = 200,
      width  = 300,
      height = 240
  }

  -- It can also read the geometry.
  local geo = client.get()[1]:geometry()
  print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

Parameters:

Name	Type(s)	Description
geo	table	A table with new coordinates, or nil.
x	integer	The horizontal position.
y	integer	The vertical position.
width	integer	The width.
height	integer	The height.

Returns:

table

Parameters:

Name		Type(s)	Description
width		integer	Desired width of client
height		integer	Desired height of client

Returns:

integer Actual width of client
integer Actual height of client

Parameters:

Name		Type(s)	Description
index		integer	The index in the list of icons to get.

Returns:

surface

Parameters:

Name		Type(s)	Description
merge	Optional	bool or function	If true then merge tags (select the client's first tag additionally) when the client is not visible. If it is a function, it will be called with the client and its first tag as arguments.

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.jumpto	granted	When a client is activated because `c:jump_to()` is called.

🔗 :append_keybinding (key)

Append a keybinding.

Parameters:

Name		Type(s)	Description
key		awful.key	The key.

Parameters:

Name		Type(s)	Description
key		awful.key	The key.

🔗 :append_mousebinding (button)

Append a mousebinding.

Parameters:

Name		Type(s)	Description
button		awful.button	The button.

🔗 :remove_mousebinding (button)

Remove a mousebinding.

Parameters:

Name		Type(s)	Description
button		awful.button	The button.

🔗 :to_primary_section ()

Move the client to the most significant layout position.

This only affects tiled clients. It will shift all other client to fill the gap caused to by the move.

Usage:

-- Spawn a client on screen #3
for i=1, 5 do
    awful.spawn("Client #"..i)
end

client.get()[5]:activate {}

client.get()[5]:to_primary_section()

🔗 :to_secondary_section ()

Move the client to the least significant layout position.

This only affects tiled clients. It will shift all other client to fill the gap caused to by the move.

Usage:

-- Spawn a client on screen #3
for i=1, 5 do
    awful.spawn("Client #"..i)
end

client.get()[1]:activate {}

client.get()[1]:to_secondary_section()

🔗 :relative_move (x, y, w, h)

Move/resize a client relative to current coordinates.

Usage example output:

Client geometry:    4   10  60  50
Client geometry:    104 110 60  50
Client geometry:    104 110 160 150

Usage example:

 awful.spawn("")

 client.get()[1].floating = true

 geo = client.get()[1]:geometry()
 print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

 client.get()[1]:relative_move(100, 100)

 geo = client.get()[1]:geometry()
 print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

 client.get()[1]:relative_move(nil, nil, 100, 100)

 geo = client.get()[1]:geometry()
 print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

Parameters:

Name		Type(s)	Description	Default value
x	Optional	integer	The relative x coordinate.	`0`
y	Optional	integer	The relative y coordinate.	`0`
w	Optional	integer	The relative width.	`0`
h	Optional	integer	The relative height.	`0`

Parameters:

Name		Type(s)	Description
target		tag	The tag to move the client to.

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.movetotag	granted	When a client could be activated because `c:move_to_tag()` was called.

🔗 :toggle_tag (target)

Toggle a tag on a client.

for tag_idx = 1, 3 do
    for _ = 1, 3 do
        awful.spawn("", {tags = {screen[1].tags[tag_idx]}})
    end
end

client.get()[1]:toggle_tag(screen[1].tags[2])

Parameters:

Name		Type(s)	Description
target		tag	The tag to move the client to.

Parameters:

Name		Type(s)	Description	Default value
s	Optional	screen	The screen, default to current + 1.	`c.screen.index+1`

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.movetoscreen	granted	When a client could be activated because `c:move_to_screen()` was called.

🔗 :to_selected_tags ()

Find suitable tags for newly created clients.

In most cases, the functionality you're actually looking for as a user will either be

c:tags(c.screen.selected_tags)

local s = awful.screen.focused()
c:move_to_screen(s)
c:tags(s.selected_tags)

Despite its naming, this is primarily used to tag newly created clients. As such, this method has no effect when applied to a client that already has tags assigned (except for emitting property::tag).

Additionally, while it is a rare case, if the client's screen has no selected tags at the point of calling this method, it will fall back to the screen's full set of tags.

awful.spawn("Client")

screen[1].tags[1].selected = false
screen[1].tags[2].selected = true
screen[1].tags[3].selected = true

-- Deselect all tags, otherwise it will do nothing.
client.get()[1]:tags{}

client.get()[1]:to_selected_tags()

Parameters:

Name		Type(s)	Description
matcher		function	A function that should return true, if a matching parent client is found.

Returns:

client or nil

Parameters:

Name		Type(s)	Description
c2		client	The parent client to check.

Returns:

client or nil

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be activate{}. This is a Lua shortcut syntax equivalent to activate({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.

Name		Type(s)	Description	Default value
args		table		Not applicable
context	Optional	string	Why was this activate called?	`"other"`
raise	Optional	boolean	Raise the client to the top of its layer and unminimize it (if needed).	`true`
force	Optional	boolean	Force the activation even for unfocusable clients.	`false`
switch_to_tags	Optional	boolean		`false`
switch_to_tag	Optional	boolean		`false`
action	Optional	boolean	Once activated, perform an action.	`false`
toggle_minimization	Optional	boolean		`false`

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	args.context	granted	Will use the context defined in `args.context`.

🔗 :grant (permission, context)

Grant a permission for a client.

Parameters:

Name		Type(s)	Description
permission		string	The permission name (just the name, no `request::`).
context		string	The reason why this permission is requested.

Parameters:

Name		Type(s)	Description
permission		string	The permission name (just the name, no `request::`).
context		string	The reason why this permission is requested.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
...			Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object

Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

Name		Type(s)	Description
name		string	The name of the signal.
func		function	The callback to call when the signal is emitted.

Signals

🔗 scanning · Class level only

Emitted when AwesomeWM is about to scan for existing clients.

Connect to this signal when code needs to be executed after screens are initialized, but before clients are added.

🔗 scanned · Class level only

Emitted when AwesomeWM is done scanning for clients.

This is emitted before the startup signal and after the scanning signal.

🔗 focus · Class level only

Emitted when a client gains focus.

🔗 list · Class level only

Emitted before request::manage, after request::unmanage, and when clients swap.

🔗 swapped

Emitted when 2 clients are swapped

Arguments:

Name		Type(s)	Description
client		client	The other client
is_source		boolean	If self is the source or the destination of the swap

🔗 request::manage · 1 permission · Class level only

Emitted when a new client appears and gets managed by Awesome.

This request should be implemented by code which track the client. It isn't recommended to use this to initialize the client content. This use case is a better fit for ruled.client, which has built-in dependency management. Using this request to mutate the client state will likely conflict with ruled.client.

Arguments:

Name	Type(s)	Description
c	client	The client.
context	string	What created the client. It is currently either "new" or "startup".
hints	table	More metadata (currently empty, it exists for compliance with the other `request::` signals).

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	border	added	granted	When a new client needs a its initial border settings.

🔗 request::unmanage · Class level only

Emitted when a client is going away.

Each places which store client objects in non-weak table or whose state depend on the current client should answer this request.

The contexts are:

user: c:unmanage() was called.
reparented: The window was reparented to another window. It is no longer a stand alone client.
destroyed: The window was closed.

Arguments:

Name	Type(s)	Description
c	client	The client.
context	string	Why was the client unmanaged.
hints	table	More metadata (currently empty, it exists for compliance with the other `request::` signals).

🔗 button::press

Emitted when a mouse button is pressed in a client.

🔗 button::release

Emitted when a mouse button is released in a client.

🔗 mouse::enter

Emitted when the mouse enters a client.

🔗 mouse::leave

Emitted when the mouse leaves a client.

🔗 mouse::move

Emitted when the mouse moves within a client.

🔗 request::activate · 1 permission · Class level only

Emitted when a client should get activated (focused and/or raised).

Contexts are:

ewmh: When a client asks for focus (from X11 events).
*autofocus.check_focus*: When autofocus is enabled (from awful.autofocus).
*autofocus.checkfocustag*: When autofocus is enabled (from awful.autofocus).
client.jumpto: When a custom lua extension asks a client to be focused (from client.jump_to).
*client.swap.global_bydirection*: When client swapping requires a focus change (from awful.client.swap.bydirection).
client.movetotag: When a client is moved to a new tag (from client.move_to_tag).
client.movetoscreen: When the client is moved to a new screen (from client.move_to_screen).
client.focus.byidx: When selecting a client using its index (from awful.client.focus.byidx).
client.focus.history.previous: When cycling through history (from awful.client.focus.history.previous).
menu.clients: When using the builtin client menu (from awful.menu.clients).
rules: When a new client is focused from a rule (from ruled.client).
screen.focus: When a screen is focused (from awful.screen.focus).

Default implementation: awful.ewmh.activate.

To implement focus stealing filters see awful.ewmh.add_activate_filter.

Arguments:

Name		Type(s)	Description	Default value
c		client	The client.	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 raised?	`false`

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	ewmh	granted	When the client asks to be activated.

Request handler:

awful.permissions.activate Activate a window.

🔗 request::autoactivate · Class level only

Emitted when an event could lead to the client being activated.

This is an layer "on top" of request::activate for event which are not actual request for activation/focus, but where "it would be nice" if the client got the focus. This includes the focus-follow-mouse model and focusing previous clients when the selected tag changes.

This idea is that request::autoactivate will emit request::activate. However it is much easier to replace the handler for request::autoactivate than it is to replace the handler for request::activate. Thus it provides a nice abstraction to simplify handling the focus when switching tags or moving the mouse.

Arguments:

Name		Type(s)	Description	Default value
c		client	The client.	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 raised?	`false`

🔗 request::geometry · 2 permissions · Class level only

Emitted when something request a client's geometry to be modified.

Arguments:

Name		Type(s)	Description	Default value
c		client	The client	Not applicable
context		string	Why and what to resize. This is used for the handlers to know if they are capable of applying the new geometry.	Not applicable
hints	Optional	table	Additional arguments. Each context handler may interpret this differently.	`{}`

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	geometry	client_maximize_horizontal	granted	When a client (programmatically) asks for the maximization to be changed.
client	geometry	client_maximize_vertical	granted	When a client (programmatically) asks for the maximization to be changed.

Request handler:

awful.permissions.geometry Move and resize the client.
awful.permissions.wibox_geometry Move and resize the wiboxes.
awful.permissions.merge_maximization Merge the 2 requests sent by clients wanting to be maximized.
awful.permissions.client_geometry_requests Allow the client to move itself.

🔗 request::tag · Class level only

Emitted when a client requests to be moved to a tag or needs a new tag.

Arguments:

Name		Type(s)	Description
c		client	The client requesting a new tag.
tag	Optional	tag	A preferred tag.
hints	Optional	table
reason	Optional	string
screen	Optional	screen

Click to display more

Request handler:

awful.permissions.tag Tag a window with its requested tag.

🔗 request::urgent · Class level only

Emitted when any client's urgent property changes.

Emitted both when urgent = true and urgent = false, so you will likely want to check c.urgent within the signal callback.

client.connect_signal("property::urgent", function(c)
    if c.urgent then
        naughty.notify {
            title = "Urgent client",
            message = c.name,
        }
    end
end)

Arguments:

Name		Type(s)	Description
c		client	The client whose property changed.

Click to display more

Request handler:

awful.permissions.urgent Handle client urgent request

🔗 request::default_mousebindings · Class level only

Emitted once to request default client mousebindings during the initial startup sequence.

This signal gives all modules a chance to register their default client mousebindings. They will then be added to all new clients, unless rules overwrite them via the buttons property.

Arguments:

Name		Type(s)	Description
context		string	The reason why the signal was sent (currently always `startup`).

🔗 request::default_keybindings · 1 permission · Class level only

Emitted once to request default client keybindings during the initial startup sequence.

This signal gives all modules a chance to register their default client keybindings. They will then be added to all new clients, unless rules overwrite them via the keys property.

Arguments:

Name		Type(s)	Description
context		string	The reason why the signal was sent (currently always

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	default_keybindings	startup	granted	Sent when AwesomeWM starts.

🔗 tagged

Emitted when a client gets tagged.

Arguments:

Name		Type(s)	Description
t		tag	The tag object.

Arguments:

Name		Type(s)	Description
t		tag	The tag object.

Arguments:

Name		Type(s)	Description	Default value
c		client	The client.	Not applicable
content	Optional	string	The context (like "rules")	`nil`
hints	Optional	table	Some hints.	`nil`

🔗 request::border · Class level only

Emitted when the border client might need to be update.

The context are:

added: When a new client is created.
active: When client gains the focus (or stop being urgent/floating but is active).
inactive: When client loses the focus (or stop being urgent/floating and is not active.
urgent: When a client becomes urgent.
floating: When the floating or maximization state changes.

Arguments:

Name	Type(s)	Description
c	client	The client.
context	string	The context.
hints	table	The hints.

Request handler:

awful.permissions.update_border The default client `request::border` handler.

Deprecated signals

🔗 manage: Use request::manage.
🔗 unmanage: Use request::unmanage.
🔗 marked: The client marked signal.
🔗 unmarked: The client unmarked signal.

Theme variables

🔗 beautiful.border_color_marked color

The border color when the client is marked. It has priority over the rest of beautiful border color properties. Note that only solid colors are supported.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_floating color

The fallback border color when the client is floating.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_maximized color

The fallback border color when the client is maximized.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_fullscreen color

The fallback border color when the client is fullscreen.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_active color

The border color when the client is active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.
naughty.notification Create a notification.
naughty.notification Create a notification.

🔗 beautiful.border_color_normal color

The border color when the client is not active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The border color.
border_color The border color.
border_color The client border color.

🔗 beautiful.border_color_urgent color

The border color when the client has the urgent property set.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_color_new color

The border color when the client is not active and new.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_floating_active color

The border color when the (floating) client is active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_floating_normal color

The border color when the (floating) client is not active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_floating_urgent color

The border color when the (floating) client has the urgent property set.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_color_floating_new color

The border color when the (floating) client is not active and new.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_maximized_active color

The border color when the (maximized) client is active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_maximized_normal color

The border color when the (maximized) client is not active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_maximized_urgent color

The border color when the (maximized) client has the urgent property set.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_color_maximized_new color

The border color when the (maximized) client is not active and new.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_fullscreen_active color

The border color when the (fullscreen) client is active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_fullscreen_normal color

The border color when the (fullscreen) client is not active.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_color_fullscreen_urgent color

The border color when the (fullscreen) client has the urgent property set.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_color_fullscreen_new color

The border color when the (fullscreen) client is not active and new.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_color The client border color.

🔗 beautiful.border_width integer

The fallback border width when nothing else is set.

Used by:

awful.widget.hotkeys_popup.widget.new Create an instance of widget with hotkeys help.

🔗 beautiful.border_width_floating integer

The fallback border width when the client is floating.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_maximized integer

The fallback border width when the client is maximized.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_normal integer

The client border width for the normal clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_active integer

The client border width for the active client.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_urgent integer

The client border width for the urgent clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_width_new integer

The client border width for the new clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_floating_normal integer

The client border width for the normal floating clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_floating_active integer

The client border width for the active floating client.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_floating_urgent integer

The client border width for the urgent floating clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_width_floating_new integer

The client border width for the new floating clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_maximized_normal integer

The client border width for the normal maximized clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_maximized_active integer

The client border width for the active maximized client.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_maximized_urgent integer

The client border width for the urgent maximized clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_width_maximized_new integer

The client border width for the new maximized clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_fullscreen_normal integer

The client border width for the normal fullscreen clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_fullscreen_active integer

The client border width for the active fullscreen client.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_fullscreen_urgent integer

The client border width for the urgent fullscreen clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.
urgent Set to `true` when the client ask for attention.

🔗 beautiful.border_width_fullscreen_new integer

The client border width for the new fullscreen clients.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.border_width_fullscreen integer

The client border width for the fullscreen clients.

This is the fallback if the more stateful version, like beautiful.border_width_fullscreen_urgent isn't set.

Used by:

awful.permissions.update_border The default client `request::border` handler.
border_width The client border width.

🔗 beautiful.opacity_normal number

The client opacity for the normal clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_active number

The client opacity for the active client.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_urgent number

The client opacity for the urgent clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_new number

The client opacity for the new clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_floating_normal number

The client opacity for the normal floating clients.

A number between 0 and 1.

Click to display more

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_floating_active number

The client opacity for the active floating client.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_floating_urgent number

The client opacity for the urgent floating clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_floating_new number

The client opacity for the new floating clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_floating number

The client opacity for the floating clients.

A number between 0 and 1. This is the fallback if the more stateful variables, like beautiful.opacity_floating_new are not set.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_maximized_normal number

The client opacity for the normal maximized clients.

A number between 0 and 1.

Click to display more

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_maximized_active number

The client opacity for the active maximized client.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_maximized_urgent number

The client opacity for the urgent maximized clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_maximized_new number

The client opacity for the new maximized clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_maximized number

The client opacity for the maximized clients.

A number between 0 and 1. This is the fallback if a more stateful variable, like beautiful.opacity_maximized_urgent, isn't set.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_fullscreen_normal number

The client opacity for the normal fullscreen clients.

A number between 0 and 1.

Click to display more

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_fullscreen_active number

The client opacity for the active fullscreen client.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_fullscreen_urgent number

The client opacity for the urgent fullscreen clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_fullscreen_new number

The client opacity for the new fullscreen clients.

A number between 0 and 1.

Used by:

awful.permissions.update_border The default client `request::border` handler.

🔗 beautiful.opacity_fullscreen number

The client opacity for the fullscreen clients.

A number between 0 and 1. This is the fallback if the variables for more stateful versions, like beautiful.opacity_fullscreen_urgent, are not set.

Used by:

awful.permissions.update_border The default client `request::border` handler.

Deprecated functions

🔗 awful.client.jumpto (c, merge)

Jump to the given client. Takes care of focussing the screen, the right tag, etc.

Parameters:

Name		Type(s)	Description
c		client	The client to jump to
merge		bool or function	If true then merge tags (select the client's first tag additionally) when the client is not visible. If it is a function, it will be called with the client and its first tag as arguments.

Parameters:

Name		Type(s)	Description	Default value
s	Optional	nil, integer or screen	The screen, or nil for all screens.	Undefined
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Returns:

table

Parameters:

Name		Type(s)	Description	Default value
s		nil, integer or screen	The screen, or nil for all screens.	Not applicable
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Returns:

table

Parameters:

Name		Type(s)	Description	Default value
s	Optional	screen	The screen.	`awful.screen.focused()`

Returns:

client

🔗 awful.client.setmaster (c)

Set the client as master: put it at the beginning of other windows.

Parameters:

Name		Type(s)	Description
c		client	The window to set as master.

🔗 awful.client.setslave (c)

Set the client as slave: put it at the end of other windows.

Parameters:

Name		Type(s)	Description
c		client	The window to set as slave.

🔗 awful.client.moveresize (x, y, w, h, c)

Move/resize a client relative to current coordinates.

Parameters:

Name		Type(s)	Description	Default value
x		integer	The relative x coordinate.	Not applicable
y		integer	The relative y coordinate.	Not applicable
w		integer	The relative width.	Not applicable
h		integer	The relative height.	Not applicable
c	Optional	client	The client, otherwise focused one is used.	`client.focus`

Parameters:

Name		Type(s)	Description
target		tag	The tag to move the client to.
c	Optional	client	The client to move, otherwise the focused one is used.

Parameters:

Name		Type(s)	Description	Default value
target		tag	The tag to toggle.	Not applicable
c	Optional	client	The client to toggle, otherwise the focused one is used.	`client.focus`

Parameters:

Name		Type(s)	Description	Default value
c	Optional	client	The client to move.	`client.focus`
s		screen	The screen, default to current + 1.	Not applicable

Parameters:

Name		Type(s)	Description
c		client	The client to mark, the focused one if not specified.

🔗 awful.client.unmark (c)

Unmark a client and then call 'unmarked' hook.

Parameters:

Name		Type(s)	Description
c		client	The client to unmark, or the focused one if not specified.

🔗 awful.client.ismarked (c)

Check if a client is marked.

Parameters:

Name		Type(s)	Description
c		client	The client to check, or the focused one otherwise.

🔗 awful.client.togglemarked (c)

Toggle a client as marked.

Parameters:

Name		Type(s)	Description
c		client	The client to toggle mark.

🔗 awful.client.getmarked ()

Return the marked clients and empty the marked table.

Returns:

table

🔗 awful.client.floating.set (c, s)

Set a client floating state, overriding auto-detection. Floating client are not handled by tiling layouts.

Parameters:

Name		Type(s)	Description
c		client	A client.
s		boolean	`true` is the client is to become floating or `false`.

🔗 awful.client.isfixed (c)

Return if a client has a fixed size or not. This function is deprecated, use c.is_fixed

Parameters:

Name		Type(s)	Description	Default value
c	Optional	client	The client.	`client.focus`

Parameters:

Name		Type(s)	Description
c		client	A client.

Returns:

boolean

Parameters:

Name		Type(s)	Description
c		client	A client.

Parameters:

Name		Type(s)	Description
c		client	A client.

Returns:

bool

🔗 awful.client.dockable.set (c, value)

Set a client's dockable state, overriding auto-detection.

With this enabled you can dock windows by moving them from the center to the edge of the workarea.

Parameters:

Name		Type(s)	Description
c		client	A client.
value		boolean	True or false.

🔗 awful.client.property.get (c, prop)

Get a client property.

This method is deprecated. It is now possible to use c.value directly.

Parameters:

Name		Type(s)	Description
c		client	The client.
prop		string	The property name.

Returns:

The property value.

🔗 awful.client.property.set (c, prop, value)

Set a client property.

This method is deprecated. It is now possible to use c.value = value directly.

Parameters:

Name	Type(s)	Description
c	client	The client.
prop	string	The property name.
value		The property value.

🔗 awful.client.run_or_raise (cmd, matcher, merge)

Switch to a client matching the given condition if running, else spawn it. If multiple clients match the given condition then the next one is focused.

Parameters:

Name	Type(s)	Description
cmd	string	The command to execute
matcher	function	A function that returns true to indicate a matching client
merge	bool or function	If true then merge tags (select the client's first tag additionally) when the client is not visible. If it is a function, it will be called with the client as argument.

Usage:

-- run or raise urxvt (perhaps, with tabs) on modkey + semicolon
awful.key({ modkey, }, 'semicolon', function ()
    local matcher = function (c)
        return ruled.client.match(c, {class = 'URxvt'})
    end
    awful.client.run_or_raise('urxvt', matcher)
end);

🔗 awful.client.get_transient_for_matching (c, matcher)

Get a matching transient_for client (if any).

Parameters:

Name		Type(s)	Description
c		client	The client.
matcher		function	A function that should return true, if a matching parent client is found.

Returns:

client or nil

Parameters:

Name		Type(s)	Description
c		client	The child client (having transient_for).
c2		client	The parent client to check.

Returns:

client or nil

Layout related functions

🔗 awful.client.idx

Calculate a client's column number, index in that column, and number of visible clients in this column.

Usage example output:

Client #1:  0   1   2
Client #2:  0   2   2
Client #3:  1   1   3
Client #4:  1   2   3
Client #5:  1   3   3

Usage example:

for i, c in ipairs(client.get()) do
    local data = awful.client.idx(c)
    print("Client #"..i..":", data.col, data.idx, data.num)
end

Parameters:

Name		Type(s)	Description
c		client	The client

Returns:

table data A table with "col", "idx" and "num" keys.
integer data.col The column number.
integer data.idx Index of the client in the column.
integer data.num The number of visible clients in the column.

🔗 awful.client.setwfact · 1 signal

Define how tall a client should be in the tile layout.

One valid use case for calling this is restoring serialized layouts. This function is rather fragile and the behavior may not remain the same across AwesomeWM versions.

When setting a value, make sure the sum remains 1. Otherwise, the clients will just go offscreen or get negative size.

awful.client.setwfact(2/3, client.get()[1])
awful.client.setwfact(1/3, client.get()[2])
awful.client.setwfact(4/8, client.get()[3])
awful.client.setwfact(2/8, client.get()[4])
awful.client.setwfact(1/8, client.get()[5])
awful.client.setwfact(1/8, client.get()[6])

Parameters:

Name		Type(s)	Description
wfact		number	The window factor value
c		client	The client

Emit signals:

property::windowfact Emitted on the c.first_tag object.

🔗 awful.client.incwfact · 1 signal

Change window factor of a client.

This will emit property::windowfact on the specific tag object c.screen.selected_tag.

Changing the gap will make some clients taller:

awful.client.incwfact(2, client.get()[4])
awful.client.incwfact(3, client.get()[2])

Parameters:

Name		Type(s)	Description	Default value
add		number	Amount to increase/decrease the client's window factor by. Should be between `-current_window_factor` and something close to infinite. Normalisation then ensures that the sum of all factors is 1.	Not applicable
c	Optional	client	The client.	`client.focus`

Click to display more

Emit signals:

property::windowfact

Extra properties available in the rules

🔗 placement N/A

The client default placement on the screen.

The default config uses:

awful.placement.no_overlap+awful.placement.no_offscreen

ruled.client.append_rule {
    rule = { class = "mplayer" },
    properties = {
        floating  = true,
        placement = awful.placement.centered,
        width     = 640,
        height    = 480,
    },
}

-- Spawn mplayer
awful.spawn("mplayer")

Tables

🔗 awful.client.object

Client class.

This table allow to add more dynamic properties to the clients. For example, doing:

 function awful.client.object.set_my_cool_property(c, value)
     -- Some logic code
     c._my_secret_my_cool_property = value
     c:emit_signal("property::my_cool_property)
 end

 function awful.client.object.get_my_cool_property()
     return c._my_secret_my_cool_property
 end

Will add a new "mycoolproperty" dyanmic property to all client. These methods will be called when an user does c.my_cool_property = "something" or set them in awdul.rules.

Note that doing this isn't required to set random properties to the client, it is only useful when setting or getting these properties require code to executed.

Fields

🔗 client.focus client

The focused client or nil (in case there is none).

It is not recommended to set the focused client using this property. Please use client.activate instead of client.focus = c. Setting the focus directly bypasses all the filters and emits fewer signals, which tend to cause unwanted side effects and make it harder to alter the code behavior in the future. It usually takes more code to use this rather than client.activate because all the boilerplate code (such as c:raise()) needs to be added everywhere.

The main use case for this field is to check when there is an active client.

 if client.focus ~= nil then
     -- do something
 end

If you want to check if a client is active, use:

 if c.active then
     -- do something
 end

lib.awful.client.focus Functions

🔗 awful.client.focus.history.delete (c)

Remove a client from the focus history

Parameters:

Name		Type(s)	Description
c		client	The client that must be removed.

🔗 awful.client.focus.byidx (i, c) · 1 permission

Focus a client by its relative index.

Usage example output:

c1:1, c2:2, c3:3, c4:4,
Call focus.byidx
c1:1, c2:2, c3:3, c4:4,
Call focus.byidx
c1:1, c2:2, c3:3, c4:4,

Usage example:

-- Print at which index each client is now at.
local function print_indices()
    color_focus()
    local output = ""

    for idx, c in ipairs(client.get()) do
         output = output .. c.name .. ":" .. idx .. ", "
    end

    print(output)
end

print_indices()

print("Call focus.byidx")
awful.client.focus.byidx(3, client.get()[1])
print_indices()

print("Call focus.byidx")
awful.client.focus.byidx(2, client.get()[4])
print_indices()

Parameters:

Name		Type(s)	Description
i			The index.
c	Optional	client	The client.

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.focus.byidx	granted	When `awful.focus.byidx` is called.

🔗 awful.client.focus.filter (c)

Filter out window that we do not want handled by focus. This usually means that desktop, dock and splash windows are not registered and cannot get focus.

Parameters:

Name		Type(s)	Description
c		client	A client.

Returns:

The same client if it's ok, nil otherwise.

🔗 awful.client.focus.history.add (c)

Update client focus history.

Parameters:

Name		Type(s)	Description
c		client	The client that has been focused.

🔗 awful.client.focus.history.get (s, idx, filter)

Get the latest focused client for a screen in history.

Parameters:

Name	Type(s)	Description
s	int or screen	The screen to look for.
idx	int	The index: 0 will return first candidate, 1 will return second, etc.
filter	function	An optional filter. If no client is found in the first iteration, awful.client.focus.filter is used by default to get any client.

Returns:

client.object

🔗 awful.client.focus.history.previous () · 1 permission

Focus the previous client in history.
Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.focus.history.previous	granted	When `awful.focus.history.previous` is called.

🔗 awful.client.focus.bydirection (dir, c, stacked) · 1 permission

Focus a client by the given direction.

-- It will go up in the same column.
awful.client.focus.bydirection("up", client.focus)

-- Nothing happens because it cannot change screen.
awful.client.focus.bydirection("right", client.focus)

-- Moves to the first column.
awful.client.focus.bydirection("left", client.focus)

Parameters:

Name		Type(s)	Description	Default value
dir		string	The direction, can be either `"up"`, `"down"`, `"left"` or `"right"`.	Not applicable
c	Optional	client	The client.	Undefined
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.focus.bydirection	granted	When `awful.focus.bydirection` is called.

🔗 awful.client.focus.global_bydirection (dir, c, stacked) · 1 permission

Focus a client by the given direction. Moves across screens.

-- It will go up in the same column.
awful.client.focus.global_bydirection("up", client.focus)

-- It will cross to screen[2].
awful.client.focus.global_bydirection("right", client.focus)

-- Moves to the first column.
awful.client.focus.global_bydirection("left", client.focus)

Parameters:

Name		Type(s)	Description	Default value
dir			The direction, can be either "up", "down", "left" or "right".	Not applicable
c	Optional	client	The client.	Undefined
stacked	Optional	boolean	Use stacking order? (top to bottom)	`false`

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	activate	client.focus.global_bydirection	granted	When awful.client.focus.global_bydirection is called.

🔗 awful.client.focus.history.is_enabled ()

Is history tracking enabled?

Returns:

bool True if history tracking is enabled.
int The number of times that tracking has been disabled.

🔗 awful.client.focus.history.enable_tracking ()

Enable history tracking.

This is the default, but can be disabled through awful.client.focus.history.disable_tracking.

Returns:

boolean

🔗 awful.client.focus.history.disable_tracking ()

Disable history tracking.

See awful.client.focus.history.enable_tracking to enable it again.

Returns:

int

disabled_count

awful.client.focus.history.enable_tracking

swap	Swap a client with another one in global client list.	object methods
swapped	Emitted when 2 clients are swapped	signals
awful.client.swap.global_bydirection	Swap a client with another client in the given direction.	static module functions
awful.client.swap.byidx	Swap a client by its relative index.	static module functions
awful.client.cycle	Cycle through the clients to change the focus.	static module functions

awful.titlebar	Create widget area on the edge of a client.	module
awful.widget.tasklist	Tasklist widget module for awful.	module

awful.widget.clienticon	Container showing the icon of a client.	module
get_icon	Get the client's n-th icon.	object methods

awful.button	Create easily new buttons objects ignoring certain modifiers.	module
append_mousebinding	Append a mousebinding.	object methods
remove_mousebinding	Remove a mousebinding.	object methods
request::default_mousebindings	Emitted once to request default client mousebindings during the initial startup sequence.	signals

awful.key	Create easily new key objects ignoring certain modifiers.	module
append_keybinding	Append a keybinding.	object methods
remove_keybinding	Remove a keybinding.	object methods
request::default_keybindings	Emitted once to request default client keybindings during the initial startup sequence.	signals

screen	A physical or virtual screen object.	module
request::activate	Emitted when a client should get activated (focused and/or raised).	signals

awful.permissions.add_activate_filter	Add an activate (focus stealing) filter function. (awful.permissions)	static module functions
awful.permissions.activate	Activate a window. (awful.permissions)	request handlers
request::activate	Emitted when a client should get activated (focused and/or raised).	signals
active	Return true if the client is active (has focus).	object properties

client.toggle_tag	Toggle a tag on a client.	object methods
tags	Access or set the client tags.	object methods

awful.spawn.once	Spawn a command if it has not been spawned before. (awful.spawn)	static module functions
awful.spawn.single_instance	Spawn a command if an instance is not already running. (awful.spawn)	static module functions
awful.spawn.raise_or_spawn	Raise a client if it exists or spawn a new one then raise it. (awful.spawn)	static module functions

tag	Labelled container where client objects can be stored.	module
new_tag	Create a new tag for this client.	extra properties available in the rules
tags	Access or set the client tags.	object methods
switch_to_tags	Unselect the current tags and select this client tags.	extra properties available in the rules

awesome

Contents

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Libraries

Sample files

Classes

Documentation

Module: client

Core components relationship

Info:

Static module functions

Returns:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

See also:

Usage:

Parameters:

See also:

Parameters:

See also:

Requested actions or permissions:

Parameters:

See also:

Parameters:

See also:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Object properties

Constraints:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

Emit signals:

Constraints:

See also:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

See also:

Usage:

Emit signals:

Constraints:

See also:

Emit signals:

Module: `client`