Class client

A process window.

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](../images/client_geo.svg)

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

Additionally to the classes described here, one can also use signals as described in signals and X properties as described in xproperties.

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

Info:

  • Copyright: 2008-2009 Julien Danjou
  • Author: Julien Danjou <julien@danjou.info>

Functions

awful.client.next (i[, sel[, stacked=false]]) Get a client by its relative index to another client.
awful.client.swap.bydirection (dir[, c=focused[, stacked=false]]) 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=false]]) Cycle clients.
awful.client.getmarked () Return the marked clients and empty the marked table.
awful.client.restore (s) 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) Returns an iterator to cycle through, starting from the client in focus or the given index, all clients that match a given criteria.
awful.client.run_or_raise (cmd, matcher, merge) Switch to a client matching the given condition if running, else spawn it.
awful.client.focus.history.disable_tracking () Disable history tracking.
awful.client.focus.history.enable_tracking () Enable history tracking.
awful.client.focus.history.is_enabled () Is history tracking enabled?

Object properties

client.window The X window id.
client.name The client title.
client.skip_taskbar True if the client does not want to be in taskbar.
client.type The window type.
client.class The client class.
client.instance The client instance.
client.pid The client PID, if available.
client.role The window role, if available.
client.machine The machine client is running on.
client.icon_name The client name when iconified.
client.icon The client icon.
client.screen Client screen.
client.hidden Define if the client must be hidden, i.e.
client.minimized Define it the client must be iconify, i.e.
client.size_hints_honor Honor size hints, e.g.
client.border_width The client border width.
client.border_color The client border color.
client.urgent The client urgent state.
client.content A cairo surface for the client window content.
client.opacity The client opacity.
client.ontop The client is on top of every other windows.
client.above The client is above normal windows.
client.below The client is below normal windows.
client.fullscreen The client is fullscreen or not.
client.maximized The client is maximized (horizontally and vertically) or not.
client.maximized_horizontal The client is maximized horizontally or not.
client.maximized_vertical The client is maximized vertically or not.
client.transient_for The client the window is transient for.
client.group_window Window identification unique to a group of windows.
client.leader_window Identification unique to windows spawned by the same command.
client.size_hints A table with size hints of the client.
client.sticky Set the client sticky, i.e.
client.modal Indicate if the client is modal.
client.focusable True if the client can receive the input focus.
client.shape_bounding The client's bounding shape as set by awesome as a (native) cairo surface.
client.shape_clip The client's clip shape as set by awesome as a (native) cairo surface.
client.shape_client_bounding The client's bounding shape as set by the program as a (native) cairo surface.
client.shape_client_clip The client's clip shape as set by the program as a (native) cairo surface.
client.startup_id The FreeDesktop StartId.
client.valid If the client that this object refers to is still managed by awesome.
client.first_tag The first tag of the client.
client.marked If a client is marked or not.
client.is_fixed Return if a client has a fixed size or not.
client.floating The client floating state.
client.x The x coordinates.
client.y The y coordinates.
client.width The width of the wibox.
client.height The height of the wibox.
client.dockable If the client is dockable.

Signals

.focus When a client gains focus.
.list Before manage, after unmanage, and when clients swap.
.swapped When 2 clients are swapped
.manage
button::press
button::release
mouse::enter
mouse::leave
mouse::move
property::window
request::activate When a client should get activated (focused and/or raised).
request::geometry
request::tag
request::urgent
.tagged When a client gets tagged.
.unfocus When a client gets unfocused.
.unmanage
.untagged When a client gets untagged.
.raised
.lowered
property::floating_geometry The last geometry when client was floating.
request::titlebars Emited when a client need to get a titlebar.
.marked The client marked signal (deprecated).
client.unmarked The client unmarked signal (deprecated).

Theme variables

beautiful.border_focus The border color when the client is focused.
beautiful.border_normal The border color when the client is not focused.
beautiful.border_width The client border width.
beautiful.border_marked The border color when the client is focused.

Deprecated functions

awful.client.jumpto Jump to the given client.
awful.client.visible Get visible clients from a screen.
awful.client.tiled Get visible and tiled clients
awful.client.moveresize Move/resize a client relative to current coordinates.
awful.client.movetotag Move a client to a tag.
awful.client.toggletag Toggle a tag on a client.
awful.client.movetoscreen Move a client to a screen.
awful.client.mark Mark a client, and then call 'marked' hook.
awful.client.unmark Unmark a client and then call 'unmarked' hook.
awful.client.ismarked Check if a client is marked.
awful.client.togglemarked Toggle a client as marked.
awful.client.floating.set Set a client floating state, overriding auto-detection.
awful.client.isfixed Return if a client has a fixed size or not.
awful.client.floating.get Get a client floating state.
awful.client.floating.toggle Toggle the floating state of a client between 'auto' and 'true'.
awful.client.dockable.get Get a client dockable state.
awful.client.dockable.set Set a client dockable state, overriding auto-detection.
awful.client.property.get Get a client property.
awful.client.property.set Set a client property.
awful.client.get_transient_for_matching Get a matching transient_for client (if any).
awful.client.is_transient_for Is a client transient for another one?

Layout related functions

awful.client.getmaster Get the master window.
awful.client.setmaster Set the client as master: put it at the beginning of other windows.
awful.client.setslave Set the client as slave: put it at the end of other windows.
awful.client.idx Calculate a client's column number, index in that column, and number of visible clients in this column.
awful.client.setwfact Set the window factor of a client
awful.client.incwfact Change window factor of a client.

Tables

client.object Client class.

Fields

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

Methods

client:struts (struts) Return client struts (reserved space at the edge of the screen).
client:buttons (buttons_table) Get or set mouse buttons bindings for a client.
client:instances () Get the number of instances.
client:get ([screen[, stacked]]) Get all clients into a table.
client:isvisible () Check if a client is visible on its screen.
client:kill () Kill a client.
client:swap (c) Swap a client with another one in global client list.
client:tags (tags_table) Access or set the client tags.
client:raise () Raise a client on top of others which are on the same layer.
client:lower () Lower a client on bottom of others which are on the same layer.
client:unmanage () Stop managing a client.
client:geometry (geo) Return or set client geometry.
client:apply_size_hints (width, height) Apply size hints to a size.
client:keys (keys_table) Get or set keys bindings for a client.
client:jump_to (merge) Jump to the given client.
client:relative_move ([x=c.x[, y=c.y[, w=c.width[, h=c.height]]]]) Move/resize a client relative to current coordinates.
client:move_to_tag (target) Move a client to a tag.
client:toggle_tag (target) Toggle a tag on a client.
client:move_to_screen ([s=c.screen.index+1]) Move a client to a screen.
client:to_selected_tags () Tag a client with the set of current tags.
client:get_transient_for_matching (matcher) Get a matching transient_for client (if any).
client:is_transient_for (c2) Is a client transient for another one?

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=false]]) Focus a client by the given direction.
awful.client.focus.global_bydirection (dir[, c[, stacked=false]]) Focus a client by the given direction.

lib.awful.client.shape Functions

awful.shape.get_transformed (c, shape_name) Get one of a client's shapes and transform it to include window decorations.
awful.shape.update.bounding (c) Update a client's bounding shape from the shape the client set itself.
awful.shape.update.clip (c) Update a client's clip shape from the shape the client set itself.
awful.shape.update.all (c) Update all of a client's shapes from the shapes the client set itself.

lib.awful.client.urgent Functions

awful.urgent.get () Get the first client that got the urgent hint.
awful.urgent.jumpto (merge) Jump to the client that received the urgent hint first.
awful.urgent.add (c, prop) Adds client to urgent stack.
awful.urgent.delete (c) Remove client from urgent stack.


Functions

Methods
awful.client.next (i[, sel[, stacked=false]])
Get a client by its relative index to another client. If no client is passed, the focused client will be used.
  • i int The index. Use 1 to get the next, -1 to get the previous.
  • sel client.object The client. (optional)
  • stacked boolean Use stacking order? (top to bottom) (default false)

Returns:

    A client, or nil if no client is available.

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=focused[, stacked=false]])
Swap a client with another client in the given direction.