# Module `awful.client`

### Info:

- Author: Julien Danjou <julien@danjou.info>
- Copyright: 2008 Julien Danjou
- Release: v3.5.1

## Functions

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

## Tables

client | Useful client manipulation functions.

## Functions

jumpto (c, merge)
  Jump to the given client. Takes care of focussing the screen, the right tag, etc.

  ### Parameters:

  - c the client to jump to
  - merge If true then merge tags when clients are not visible.
client.urgent.get ()
  Get the first client that got the urgent hint.

  ### Returns:

  The first urgent client.
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.
client.urgent.add (c, prop)
  Adds client to urgent stack.

  ### Parameters:

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

  ### Parameters:

  - c The client object.
client.focus.history.delete (c)
  Remove a client from the focus history

  ### Parameters:

  - c The client that must be removed.
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.

  ### Returns:

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

  ### Parameters:

  - c The client that has been focused.
client.focus.history.get (screen, idx)
  Get the latest focused client for a screen in history. 1 will return second, etc.

  ### Parameters:

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

  ### Returns:

  A client.
client.focus.history.previous ()
  Focus the previous client in history.
visible (screen)
  Get visible clients from a screen.

  ### Parameters:

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

  ### Returns:

  A table with all visible clients.
tiled (screen)
  Get visible and tiled clients

  ### Parameters:

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

  ### Returns:

  A table with all visible and tiled clients.
next (i, c)
  Get a client by its relative index to the focused window.

  ### Parameters:

  - i The index.
  - c Optional client.

  ### Returns:

  A client, or nil if no client is available.

  ### Usage:

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

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.
client.focus.global_bydirection (dir, c)
  Focus a client by the given direction. Moves across screens.

  ### Parameters:

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

  ### Parameters:

  - i The index.
  - c Optional client.
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.
client.swap.global_bydirection (dir, c)
  Swap a client with another client in the given direction. Swaps across screens.

  ### Parameters:

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

  ### Parameters:

  - i The index.
  - c Optional client, otherwise focused one is used.
cycle (clockwise, screen)
  Cycle clients.

  ### Parameters:

  - clockwise True to cycle clients clockwise.
  - screen Optional screen where to cycle clients.
getmaster (screen)
  Get the master window.

  ### Parameters:

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

  ### Returns:

  The master window.
setmaster (c)
  Set the client as master: put it at the beginning of other windows.

  ### Parameters:

  - c The window to set as master.
setslave (c)
  Set the client as slave: put it at the end of other windows.

  ### Parameters:

  - c The window to set as slave.
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.
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.
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.
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.
mark (c)
  Mark a client, and then call 'marked' hook.

  ### Parameters:

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

  ### Returns:

  True if the client has been marked. False if the client was already marked.
unmark (c)
  Unmark a client and then call 'unmarked' hook.

  ### Parameters:

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

  ### Returns:

  True if the client has been unmarked. False if the client was not marked.
ismarked (c)
  Check if a client is marked.

  ### Parameters:

  - c The client to check, or the focused one otherwise.
togglemarked (c)
  Toggle a client as marked.

  ### Parameters:

  - c The client to toggle mark.
getmarked ()
  Return the marked clients and empty the marked table.

  ### Returns:

  A table with all marked clients.
client.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.
isfixed (c)
  Return if a client has a fixe size or not.

  ### Parameters:

  - c The client.
client.floating.get (c)
  Get a client floating state. did not set them manually. For example, windows with a type different than normal.

  ### Parameters:

  - c A client.

  ### Returns:

  True or false. Note that some windows might be floating even if you
client.floating.toggle (c)
  Toggle the floating state of a client between 'auto' and 'true'.

  ### Parameters:

  - c A client.
client.floating.delete (c)
  Remove the floating information on a client.

  ### Parameters:

  - c The client.
restore (s)
  Restore (=unminimize) a random client.

  ### Parameters:

  - s The screen to use.

  ### Returns:

  The restored client if some client was restored, otherwise nil.
idx (c)
  Calculate a client's column number, index in that column, and number of visible clients in this column.

  ### Parameters:

  - c the client

  ### Returns:

  1. col the column number
  2. idx index of the client in the column
  3. num the number of visible clients in the column
setwfact (wfact, c)
  Set the window factor of a client

  ### Parameters:

  - wfact the window factor value
  - c the client
incwfact (add, c)
  Increment a client's window factor

  ### Parameters:

  - add amount to increase the client's window
  - c the client
client.dockable.get (c)
  Get a client dockable state. did not set them manually. For example, windows with a type "utility", "toolbar" or "dock"

  ### Parameters:

  - c A client.

  ### Returns:

  True or false. Note that some windows might be dockable even if you
client.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.
client.property.get (c, prop)
  Get a client property.

  ### Parameters:

  - c The client.
  - prop The property name.

  ### Returns:

  The property.
client.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.
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.

  ### 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
       <p><code>
       local urxvt = function (c) <br/>
         return awful.rules.match(c, {class = "URxvt"}) <br/>
       end <br/>
       </br>
       for c in awful.client.iterate(urxvt) do <br/>
         c.minimized = false <br/>
       end <br/>
       </code></p>

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.

  ### Parameters:

  - cmd the command to execute
  - matcher a function that returns true to indicate a matching client
  - merge if true then merge tags when clients are not visible

  ### Usage:

       run or raise urxvt (perhaps, with tabs) on modkey + semicolon
       <p><code>
       awful.key({ modkey, }, 'semicolon', function ()            <br/>
         local matcher = function (c)                             <br/>
           return awful.rules.match(c, {class = 'URxvt'}) <br/>
         end                                                      <br/>
         awful.client.run_or_raise('urxvt', matcher)
       end);
       </code></p>

## Tables

client
  Useful client manipulation functions. awful.client

generated by LDoc 1.3