Reference

# Module `awful.client`

Useful client manipulation functions.

Author:

Julien Danjou <julien@danjou.info>

Copyright© 2008 Julien Danjou

Release: v3.4.13

## Functions

cycle (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.
cycle (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.
dockable.get (c) | Get a client dockable state.
dockable.set (c, value) | Set a client dockable state, overriding auto-detection.
floating.delete (c) | Remove the floating information on a client.
floating.get (c) | Get a client floating state.
floating.set (c, s) | Set a client floating state, overriding auto-detection.
floating.toggle (c) | Toggle the floating state of a client between 'auto' and 'true'.
focus.bydirection (dir, c) | Focus a client by the given direction.
focus.byidx (i, c) | Focus a client by its relative index.
focus.filter (c) | Filter out window that we do not want handled by focus.
focus.history.add (c) | Update client focus history.
focus.history.delete (c) | Remove a client from the focus history
focus.history.get (screen, idx) | Get the latest focused client for a screen in history.
focus.history.previous () | Focus the previous client in history.
getmarked () | Return the marked clients and empty the marked table.
getmaster (screen) | Get the master window.
idx (c) | Calculate a client's column number, index in that column, and number of visible clients in this column.
incwfact (add, c) | Increment a client's window factor
isfixed (c) | Return if a client has a fixe size or not.
ismarked (c) | Check if a client is marked.
mark (c) | Mark a client, and then call 'marked' hook.
moveresize (x, y, w, h, c) | Move/resize a client relative to current coordinates.
movetoscreen (c, s) | Move a client to a screen.
movetotag (target, c) | Move a client to a tag.
next (i, c) | Get a client by its relative index to the focused window.
property.get (c, prop) | Get a client property.
property.set (c, prop, value) | Set a client property.
restore (s) | Restore (=unminimize) a random client.
setslave (c) | Set the client as slave: put it at the end of other windows.
setwfact (wfact, c) | Set the window factor of a client
swap.bydirection (dir, c) | Swap a client with another client in the given direction
swap.byidx (i, c) | Swap a client by its relative index.
tiled (screen) | Get visible and tiled clients
togglemarked (c) | Toggle a client as marked.
toggletag (target, c) | Toggle a tag on a client.
unmark (c) | Unmark a client and then call 'unmarked' hook.
urgent.add (c, prop) | Adds client to urgent stack.
urgent.delete (c) | Remove client from urgent stack.
urgent.get () | Get the first client that got the urgent hint.
urgent.jumpto (merge) | Jump to the client that received the urgent hint first.
visible (screen) | Get visible clients from a screen.

## Functions

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

  ### Parameters

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

  e.g.: un-minimize all urxvt instances

  `local urxvt = function (c)
  return awful.rules.match(c, {class = "URxvt"})
  end
  for c in awful.client.cycle(urxvt) do
  c.minimized = false
  end
  `

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

  ### Parameters

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

  e.g.: un-minimize all urxvt instances

  `local urxvt = function (c)
  return awful.rules.match(c, {class = "URxvt"})
  end
  for c in awful.client.cycle(urxvt) do
  c.minimized = false
  end
  `

dockable.get (c)
  Get a client dockable state.

  ### Parameters

  - c: A client.

  ### Return value:

  True or false. Note that some windows might be dockable even if you did not set them manually. For example, windows with a type "utility", "toolbar" or "dock"
dockable.set (c, value)
  Set a client 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

  - c: A client.
  - value: True or false.
floating.delete (c)
  Remove the floating information on a client.

  ### Parameters

  - c: The client.
floating.get (c)
  Get a client floating state.

  ### Parameters

  - c: A client.

  ### Return value:

  True or false. Note that some windows might be floating even if you did not set them manually. For example, windows with a type different than normal.
floating.set (c, s)
  Set a client floating state, overriding auto-detection. Floating client are not handled by tiling layouts.

  ### Parameters

  - c: A client.
  - s: True or false.
floating.toggle (c)
  Toggle the floating state of a client between 'auto' and 'true'.

  ### Parameters

  - c: A client.
focus.bydirection (dir, c)
  Focus a client by the given direction.

  ### Parameters

  - dir: The direction, can be either "up", "down", "left" or "right".
  - c: Optional client.
focus.byidx (i, c)
  Focus a client by its relative index.

  ### Parameters

  - i: The index.
  - c: Optional 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

  - c: A client.

  ### Return value:

  The same client if it's ok, nil otherwise.
focus.history.add (c)
  Update client focus history.

  ### Parameters

  - c: The client that has been focused.
focus.history.delete (c)
  Remove a client from the focus history

  ### Parameters

  - c: The client that must be removed.
focus.history.get (screen, idx)
  Get the latest focused client for a screen in history.

  ### Parameters

  - screen: The screen number to look for.
  - idx: The index: 0 will return first candidate, 1 will return second, etc.

  ### Return value:

  A client.
focus.history.previous ()
  Focus the previous client in history.
getmarked ()
  Return the marked clients and empty the marked table.

  ### Return value:

  A table with all marked clients.
getmaster (screen)
  Get the master window.

  ### Parameters

  - screen: Optional screen number, otherwise screen mouse is used.

  ### Return value:

  The master window.
idx (c)
  Calculate a client's column number, index in that column, and number of visible clients in this column.

  ### Parameters

  - c: the client

  ### Return values:

  1. col the column number
  2. idx index of the client in the column
  3. num the number of visible clients in the column
incwfact (add, c)
  Increment a client's window factor

  ### Parameters

  - add: amount to increase the client's window
  - c: the client
isfixed (c)
  Return if a client has a fixe size or not.

  ### Parameters

  - c: The client.
ismarked (c)
  Check if a client is marked.

  ### Parameters

  - c: The client to check, or the focused one otherwise.
mark (c)
  Mark a client, and then call 'marked' hook.

  ### Parameters

  - c: The client to mark, the focused one if not specified.

  ### Return value:

  True if the client has been marked. False if the client was already marked.
moveresize (x, y, w, h, c)
  Move/resize a client relative to current coordinates.

  ### Parameters

  - x: The relative x coordinate.
  - y: The relative y coordinate.
  - w: The relative width.
  - h: The relative height.
  - c: The optional client, otherwise focused one is used.
movetoscreen (c, s)
  Move a client to a screen. Default is next screen, cycling.

  ### Parameters

  - c: The client to move.
  - s: The screen number, default to current + 1.
movetotag (target, c)
  Move a client to a tag.

  ### Parameters

  - target: The tag to move the client to.
  - c: Optional client to move, otherwise the focused one is used.
next (i, c)
  Get a client by its relative index to the focused window.

  ### Parameters

  - i: The index.
  - c: Optional client.

  ### Usage:

  Set i to 1 to get next, -1 to get previous.

  ### Return value:

  A client, or nil if no client is available.
property.get (c, prop)
  Get a client property.

  ### Parameters

  - c: The client.
  - prop: The property name.

  ### Return value:

  The property.
property.set (c, prop, value)
  Set a client property. This properties are internal to awful. Some are used to move clients, etc.

  ### Parameters

  - c: The client.
  - prop: The property name.
  - value: The value.
restore (s)
  Restore (=unminimize) a random client.

  ### Parameters

  - s: The screen to use.

  ### Return value:

  True if some client was restored.
setslave (c)
  Set the client as slave: put it at the end of other windows.

  ### Parameters

  - c: The window to set as slave.
setwfact (wfact, c)
  Set the window factor of a client

  ### Parameters

  - wfact: the window factor value
  - c: the client
swap.bydirection (dir, c)
  Swap a client with another client in the given direction

  ### Parameters

  - dir: The direction, can be either "up", "down", "left" or "right".
  - c: Optional client.
swap.byidx (i, c)
  Swap a client by its relative index.

  ### Parameters

  - i: The index.
  - c: Optional client, otherwise focused one is used.
tiled (screen)
  Get visible and tiled clients

  ### Parameters

  - screen: The screen number, or nil for all screens.

  ### Return value:

  A tabl with all visible and tiled clients.
togglemarked (c)
  Toggle a client as marked.

  ### Parameters

  - c: The client to toggle mark.
toggletag (target, c)
  Toggle a tag on a client.

  ### Parameters

  - target: The tag to toggle.
  - c: Optional client to toggle, otherwise the focused one is used.
unmark (c)
  Unmark a client and then call 'unmarked' hook.

  ### Parameters

  - c: The client to unmark, or the focused one if not specified.

  ### Return value:

  True if the client has been unmarked. False if the client was not marked.
urgent.add (c, prop)
  Adds client to urgent stack.

  ### Parameters

  - c: The client object.
  - prop: The property which is updated.
urgent.delete (c)
  Remove client from urgent stack.

  ### Parameters

  - c: The client object.
urgent.get ()
  Get the first client that got the urgent hint.

  ### Return value:

  The first urgent client.
urgent.jumpto (merge)
  Jump to the client that received the urgent hint first.

  ### Parameters

  - merge: If true then merge tags when clients are not visible.
visible (screen)
  Get visible clients from a screen.

  ### Parameters

  - screen: The screen number, or nil for all screens.

  ### Return value:

  A table with all visible clients.