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

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 <[email protected]>

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.icon_sizes The available sizes of client icons.
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_input The client’s input 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 client.
client.height The height of the client.
client.dockable If the client is dockable.
client.shape Set the client shape.

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::size When the height or width changed.
property::position When the x or y coordinate changed.
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’s dockable state.
awful.client.dockable.set Set a client’s 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:get_icon (index) Get the client’s n-th icon.
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.client.shape.get_transformed (c, shape_name) Get one of a client’s shapes and transform it to include window decorations.
awful.client.shape.update.all (c) Update all of a client’s shapes from the shapes the client set itself.
awful.client.shape.update.bounding (c) Update a client’s bounding shape from the shape the client set itself.
awful.client.shape.update.clip (c) Update a client’s clip shape from the shape 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.
  • dir string The direction, can be either “up”, “down”, “left” or “right”.
  • c client.object The client. (default focused)
  • stacked boolean Use stacking order? (top to bottom) (default false)
awful.client.swap.global_bydirection (dir[, sel])
Swap a client with another client in the given direction. Swaps across screens.
  • dir The direction, can be either “up”, “down”, “left” or “right”.
  • sel client.object The client. (optional)
awful.client.swap.byidx (i[, c])
Swap a client by its relative index.
  • i The index.
  • c client.object The client, otherwise focused one is used. (optional)
awful.client.cycle (clockwise[, s[, stacked=false]])
Cycle clients.
  • clockwise True to cycle clients clockwise.
  • s The screen where to cycle clients. (optional)
  • stacked boolean Use stacking order? (top to bottom) (default false)
awful.client.getmarked ()
Return the marked clients and empty the marked table.

Returns:

    A table with all marked clients.
awful.client.restore (s)
Restore (=unminimize) a random client.
  • s The screen to use.

Returns:

    The restored client if some client was restored, otherwise nil.
awful.client.property.persist (prop, kind)
Set a client property to be persistent across restarts (via X properties).
  • prop The property name.
  • kind The type (used for register_xproperty). One of “string”, “number” or “boolean”.
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.
  • filter a function that returns true to indicate a positive match
  • start what index to start iterating from. Defaults to using the index of the currently focused client.
  • s which screen to use. nil means all screens.

Usage:

    -- un-minimize all urxvt instances
    local urxvt = function (c)
      return awful.rules.match(c, {class = "URxvt"})
    end
    
    for c in awful.client.iterate(urxvt) do
      c.minimized = false
    end
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 focussed.
  • cmd the command to execute
  • matcher 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 awful.rules.match(c, {class = 'URxvt'})
        end
        awful.client.run_or_raise('urxvt', matcher)
    end);
awful.client.focus.history.disable_tracking ()
Disable history tracking.

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

Returns:

    int The internal value of disabled_count (calls to this function without calling awful.client.focus.history.enable_tracking).
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 True if history tracking has been enabled.
awful.client.focus.history.is_enabled ()
Is history tracking enabled?

Returns:

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

Object properties

client.window

The X window id.

Signal:

  • property::window

Type:

  • string
client.name

The client title.

Signal:

  • property::name

Type:

  • string
client.skip_taskbar

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

Signal:

  • property::skip_taskbar

Type:

  • boolean
client.type

The window type.

Valid types are:

  • 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

Signal:

  • property::type

Type:

  • string
client.class

The client class.

If the client has multiple classes, the first one is used.

To get a client class from the command line, use te xprop command.

Signal:

  • property::class

Type:

  • string
client.instance

The client instance.

Signal:

  • property::instance

Type:

  • string
client.pid

The client PID, if available.

Signal:

  • property::pid

Type:

  • number
client.role

The window role, if available.

Signal:

  • property::role

Type:

  • string
client.machine

The machine client is running on.

Signal:

  • property::machine

Type:

  • string
client.icon_name

The client name when iconified.

Signal:

  • property::icon_name

Type:

  • string
client.icon

The client icon.

Signal:

  • property::icon

Type:

  • surface
client.icon_sizes

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

Signal:

  • property::icon_sizes

Type:

See also:

client.screen

Client screen.

Signal:

  • property::screen

Type:

  • screen
client.hidden

Define if the client must be hidden, i.e. never mapped, invisible in taskbar.

Signal:

  • property::hidden

Type:

  • boolean
client.minimized

Define it the client must be iconify, i.e. only visible in taskbar.

Signal:

  • property::minimized

Type:

  • boolean
client.size_hints_honor

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 awful.rules.

Signal:

  • property::size_hints_honor

Type:

  • boolean

See also:

client.border_width
The client border width.

Type:

  • integer
client.border_color

The client border color.

Signal:

  • property::border_color

Type:

  • pattern Any string, gradients and patterns will be converted to a cairo pattern.

See also:

client.urgent

The client urgent state.

Signal:

  • property::urgent

Type:

  • boolean
client.content

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)

Type:

  • surface
client.opacity

The client opacity.

Signal:

  • property::opacity

Type:

  • number Between 0 (transparent) to 1 (opaque)
client.ontop
The client is on top of every other windows.

Type:

  • boolean
client.above

The client is above normal windows.

Signal:

  • property::above

Type:

  • boolean
client.below

The client is below normal windows.

Signal:

  • property::below

Type:

  • boolean
client.fullscreen

The client is fullscreen or not.

Signal:

  • property::fullscreen

Type:

  • boolean
client.maximized

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

Signal:

  • property::maximized

Type:

  • boolean
client.maximized_horizontal

The client is maximized horizontally or not.

Signal:

  • property::maximized_horizontal

Type:

  • boolean
client.maximized_vertical

The client is maximized vertically or not.

Signal:

  • property::maximized_vertical

Type:

  • boolean
client.transient_for

The client the window is transient for.

Signal:

  • property::transient_for

Type:

  • client
client.group_window

Window identification unique to a group of windows.

Signal:

  • property::group_window

Type:

  • client
client.leader_window
Identification unique to windows spawned by the same command.

Type:

  • client
client.size_hints

A table with size hints of the client.

Signal:

  • property::size_hints

Type:

  • table
    • user_position integer
    • user_size integer
    • program_position integer
    • program_size integer
    • max_width integer
    • max_height integer
    • min_width integer
    • min_height integer
    • width_inc integer
    • height_inc integer

See also:

client.sticky

Set the client sticky, i.e. available on all tags.

Signal:

  • property::sticky

Type:

  • boolean
client.modal

Indicate if the client is modal.

Signal:

  • property::modal

Type:

  • boolean
client.focusable

True if the client can receive the input focus.

Signal:

  • property::focusable

Type:

  • boolean
client.shape_bounding

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

Signal:

  • property::shape_bounding

Type:

  • surface

See also:

client.shape_clip

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

Signal:

  • property::shape_clip

Type:

  • surface
client.shape_input

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

Signal:

  • property::shape_input

Type:

  • surface
client.shape_client_bounding

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

Signal:

  • property::shape_client_bounding

Type:

  • surface
client.shape_client_clip

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

Signal:

  • property::shape_client_clip

Type:

  • surface
client.startup_id

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.

Signal:

  • property::startup_id

Type:

  • string
client.valid

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

Signal:

  • property::valid

Type:

  • boolean
client.first_tag

The first tag of the client. Optimized form of c:tags()[1].

Signal:

  • property::first_tag

Type:

  • tag
client.marked

If a client is marked or not.

Signal:

  • marked (for legacy reasons, use property::marked)
  • unmarked (for legacy reasons, use property::marked)
  • property::marked

Type:

  • boolean
client.is_fixed
Return if a client has a fixed size or not.

Signal:

  • property::is_fixed

This property is read only.

Type:

  • boolean The fixed size state

See also:

client.floating

The client floating state. If the client is part of the tiled layout or free floating.

Note that some windows might be floating even if you did not set them manually. For example, windows with a type different than normal.

Signal:

  • property::floating

Type:

  • boolean The floating state
client.x

The x coordinates.

Signal:

  • property::x

Type:

  • integer
client.y

The y coordinates.

Signal:

  • property::y

Type:

  • integer
client.width

The width of the client.

Signal:

  • property::width

Type:

  • width
client.height

The height of the client.

Signal:

  • property::height

Type:

  • height
client.dockable

If the client is dockable.

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

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

Signal:

  • property::dockable

Type:

  • boolean The dockable state
client.shape
Set the client shape.

Type:

  • A gears.shape gears.shape compatible function.

See also:

Signals

.focus
When a client gains focus.
.list
Before manage, after unmanage, and when clients swap.
.swapped
When 2 clients are swapped

Arguments:

  • client client The other client
  • is_source boolean If self is the source or the destination of the swap
.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).

Contexts are:

  • ewmh: When a client asks for focus (from X11 events).
  • autofocus.check_focus: When autofocus is enabled (from awful.autofocus).
  • autofocus.check_focus_tag: 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 awful.rules).
  • 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:

  • context string The context where this signal was used.
  • hints A table with additional hints:
    • raise boolean should the client be raised? (default false)
request::geometry

Arguments:

  • c client The client
  • context string Why and what to resize. This is used for the handlers to know if they are capable of applying the new geometry.
  • Additional table arguments. Each context handler may interpret this differently. (default {})
request::tag
request::urgent
.tagged
When a client gets tagged.

Arguments:

  • t tag The tag object.
.unfocus
When a client gets unfocused.
.unmanage
.untagged
When a client gets untagged.

Arguments:

  • t tag The tag object.
.raised
.lowered
property::size
When the height or width changed.

See also:

property::position
When the x or y coordinate changed.

See also:

property::floating_geometry
The last geometry when client was floating.
request::titlebars
Emited when a client need to get a titlebar.

Arguments:

  • content string The context (like “rules”) (default nil)
  • hints table Some hints. (default nil)
.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.

Type:

  • string
beautiful.border_normal
The border color when the client is not focused.

Type:

  • string
beautiful.border_width
The client border width.

Type:

  • integer
beautiful.border_marked
The border color when the client is focused.

Type:

  • string

Deprecated functions

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

param:

  • c client.object 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.

See also:

awful.client.visible
Get visible clients from a screen.

param:

  • s integer or screen The screen, or nil for all screens. (optional)
  • stacked boolean Use stacking order? (top to bottom) (default false)

See also:

awful.client.tiled
Get visible and tiled clients

param:

  • s integer or screen The screen, or nil for all screens.
  • stacked boolean Use stacking order? (top to bottom) (default false)

See also:

awful.client.moveresize
Move/resize a client relative to current coordinates.

param:

  • x The relative x coordinate.
  • y The relative y coordinate.
  • w The relative width.
  • h The relative height.
  • c client.object The client, otherwise focused one is used. (optional)

See also:

awful.client.movetotag
Move a client to a tag.

param:

  • target The tag to move the client to.
  • c client.object The client to move, otherwise the focused one is used. (optional)

See also:

awful.client.toggletag
Toggle a tag on a client.

param:

  • target The tag to toggle.
  • c client.object The client to toggle, otherwise the focused one is used. (optional)

See also:

awful.client.movetoscreen
Move a client to a screen. Default is next screen, cycling.

param:

  • c client.object The client to move.
  • s The screen, default to current + 1.

See also:

awful.client.mark
Mark a client, and then call ‘marked’ hook.

param:

  • c client.object The client to mark, the focused one if not specified.
awful.client.unmark
Unmark a client and then call ‘unmarked’ hook.

param:

  • c client.object The client to unmark, or the focused one if not specified.
awful.client.ismarked
Check if a client is marked.

param:

  • c client.object The client to check, or the focused one otherwise.
awful.client.togglemarked
Toggle a client as marked.

param:

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

param:

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

param:

See also:

awful.client.floating.get
Get a client floating state.

param:

See also:

awful.client.floating.toggle
Toggle the floating state of a client between ‘auto’ and ‘true’. Use c.floating = not c.floating

param:

See also:

awful.client.dockable.get
Get a client’s dockable state.

param:

awful.client.dockable.set
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.

param:

awful.client.property.get
Get a client property.

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

param:

awful.client.property.set
Set a client property.

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

param:

  • c client.object The client.
  • prop The property name.
  • value The value.
awful.client.get_transient_for_matching
Get a matching transient_for client (if any).

param:

  • c client.object The client.
  • matcher function A function that should return true, if a matching parent client is found.

See also:

awful.client.is_transient_for
Is a client transient for another one?

param:

See also:

Layout related functions

awful.client.getmaster
Get the master window.

param:

  • _or_idx screen [opt=awful.screen.focused()] s The screen.
awful.client.setmaster
Set the client as master: put it at the beginning of other windows.

param:

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

param:

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

param:

awful.client.setwfact
Set the window factor of a client

param:

awful.client.incwfact
Change window factor of a client.

param:

  • add number Amount to increase/decrease the client’s window factor. Should be between -current_window_factor and something close to infinite. The normalisation then ensures that the sum of all factors is 1.
  • c client.object the 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).
  • struts A table with new strut values, or none.

Returns:

    A table with strut values.
client:buttons (buttons_table)
Get or set mouse buttons bindings for a client.
  • buttons_table An array of mouse button bindings objects, or nothing.

Returns:

    A table with all buttons.
client:instances ()
Get the number of instances.

Returns:

    The number of client objects alive.
client:get ([screen[, stacked]])
Get all clients into a table.
  • screen integer A screen number to filter clients on. (optional)
  • stacked boolean Return clients in stacking order? (ordered from top to bottom). (optional)

Returns:

    table A table with clients.
client:isvisible ()
Check if a client is visible on its screen.

Returns:

    A boolean value, true if the client is visible, false otherwise.
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.

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

Signal:

  • property::tags
  • tags_table table A table with tags to set, or nil to get the current tags.

Returns:

    table A table with all 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.
  • geo table or nil A table with new coordinates, or nil.

Returns:

    table A table with client geometry and coordinates.
client:apply_size_hints (width, height)
Apply size hints to a size.
  • width Desired width of client
  • height Desired height of client

Returns:

  1. Actual width of client
  2. Actual height of client
client:keys (keys_table)
Get or set keys bindings for a client.
  • keys_table An array of key bindings objects, or nothing.

Returns:

    A table with all keys.
client:get_icon (index)

Get the client’s n-th icon.

Signal:

  • property::icon
  • index interger The index in the list of icons to get.

Returns:

    surface A lightuserdata for a cairo surface. This reference must be destroyed!
client:jump_to (merge)
Jump to the given client. Takes care of focussing the screen, the right tag, etc.
  • 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.
client:relative_move ([x=c.x[, y=c.y[, w=c.width[, h=c.height]]]])
Move/resize a client relative to current coordinates.
  • x number The relative x coordinate. (default c.x)
  • y number The relative y coordinate. (default c.y)
  • w number The relative width. (default c.width)
  • h number The relative height. (default c.height)

See also:

client:move_to_tag (target)
Move a client to a tag.
  • target tag The tag to move the client to.
client:toggle_tag (target)
Toggle a tag on a client.
  • target tag The tag to move the client to.
client:move_to_screen ([s=c.screen.index+1])
Move a client to a screen. Default is next screen, cycling.
  • s screen The screen, default to current + 1. (default c.screen.index+1)

See also:

client:to_selected_tags ()
Tag a client with the set of current tags.

See also:

client:get_transient_for_matching (matcher)
Get a matching transient_for client (if any).
  • matcher function A function that should return true, if a matching parent client is found.

Returns:

    client.client or nil The matching parent client or nil.
client:is_transient_for (c2)
Is a client transient for another one?

Returns:

    client.client or nil The parent client or nil.

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. This usually means that desktop, dock and splash windows are not registered and cannot get focus.

Returns:

    The same client if it’s ok, nil otherwise.
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.
  • 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 A client.
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.
  • dir string The direction, can be either "up", "down", "left" or "right".
  • c client.object The client. (optional)
  • stacked boolean Use stacking order? (top to bottom) (default false)
awful.client.focus.global_bydirection (dir[, c[, stacked=false]])
Focus a client by the given direction. Moves across screens.
  • dir The direction, can be either “up”, “down”, “left” or “right”.
  • c client.object The client. (optional)
  • stacked boolean Use stacking order? (top to bottom) (default false)

lib.awful.client.shape Functions

awful.client.shape.get_transformed (c, shape_name)
Get one of a client’s shapes and transform it to include window decorations.
  • c client.object The client whose shape should be retrieved
  • shape_name string Either “bounding” or “clip”
awful.client.shape.update.all (c)
Update all of a client’s shapes from the shapes the client set itself.
awful.client.shape.update.bounding (c)
Update a client’s bounding shape from the shape the client set itself.
awful.client.shape.update.clip (c)
Update a client’s clip shape from the shape the client set itself.

lib.awful.client.urgent Functions

awful.urgent.get ()
Get the first client that got the urgent hint.

Returns:

    client.object The first urgent client.
awful.urgent.jumpto (merge)
Jump to the client that received the urgent hint first.
  • 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.
awful.urgent.add (c, prop)
Adds client to urgent stack.
  • c client.object The client object.
  • prop The property which is updated.
awful.urgent.delete (c)
Remove client from urgent stack.
generated by LDoc 1.4.6 Last updated 2017-06-21 07:21:06