# Module `awful.placement`

Algorithms used to place various drawables.

The functions provided by this module all follow the same arguments conventions. This allow:

- To use them in various other module as visitor objects
- Turn each function into an API with various common customization parameters.
- Re-use the same functions for the mouse, clients, screens and wiboxes

### Compositing

It is possible to compose placement function using the `+` or `*` operator:

    -- 'right' will be replaced by 'left'
    local f = (awful.placement.right + awful.placement.left)
    f(client.focus)

    -- Simulate Windows 7 'edge snap' (also called aero snap) feature
    local axis = 'vertically'
    local f = awful.placement.scale
      + awful.placement.left
      + (axis and awful.placement['maximize_'..axis] or nil)
    local geo = f(client.focus, {honor_workarea=true, to_percent = 0.5})

### Common arguments

pretend (boolean):

Do not apply the new geometry. This is useful if only the return values is necessary.

honor_workarea (boolean):

Take workarea into account when placing the drawable (default: false)

honor_padding (boolean):

Take the screen padding into account (see screen.padding)

tag (tag):

Use a tag geometry

margins (number or table):

A table with left, right, top, bottom keys or a number

parent (client, wibox, mouse or screen):

A parent drawable to use a base geometry

bounding_rect (table):

A bounding rectangle

attach (boolean):

When the parent geometry (like the screen) changes, re-apply the placement function. This will add a `detach_callback` function to the drawable. Call this to detach the function. This will be called automatically when a new attached function is set.

offset (table or number):

The offset(s) to apply to the new geometry.

store_geometry (boolean):

Keep a single history of each type of placement. It can be restored using awful.placement.restore by setting the right `context` argument.

When either the parent or the screen geometry change, call the placement function again.

update_workarea (boolean):

If attach is true, also update the screen workarea.

### Info:

- Copyright: 2008 Julien Danjou, Emmanuel Lepage Vallee 2016
- Author: Emmanuel Lepage Vallee <elv1313@gmail.com>,Julien Danjou <julien@danjou.info>

## Functions

closest_corner ([d=client.focus[, args={}]]) | Move a drawable to the closest corner of the parent geometry (such as the screen).
no_offscreen (c[, screen=client's screen]) | Place the client so no part of it will be outside the screen (workarea).
no_overlap (c) | Place the client where there's place available with minimum overlap.
under_mouse (d[, args={}]) | Place the client under the mouse.
next_to_mouse (d[, args={}]) | Place the client next to the mouse.
resize_to_mouse (d[, args={}]) | Resize the drawable to the cursor.
align (d[, args={}]) | Move the drawable (client or wibox) `d` to a screen position or side.
top_left (d[, args={}]) | Align a client to the top left of the parent area.
top_right (d[, args={}]) | Align a client to the top right of the parent area.
bottom_left (d[, args={}]) | Align a client to the bottom left of the parent area.
bottom_right (d[, args={}]) | Align a client to the bottom right of the parent area.
left (d[, args={}]) | Align a client to the left of the parent area.
right (d[, args={}]) | Align a client to the right of the parent area.
top (d[, args={}]) | Align a client to the top of the parent area.
bottom (d[, args={}]) | Align a client to the bottom of the parent area.
centered (d[, args={}]) | Align a client to the center of the parent area.
center_vertical (d[, args={}]) | Align a client to the vertical center of the parent area.
center_horizontal (d[, args={}]) | Align a client to the horizontal center left of the parent area.
stretch ([d=client.focus[, args={}]]) | Stretch a drawable in a specific direction.
stretch_left (d[, args={}]) | Stretch the drawable to the left of the parent area.
stretch_right (d[, args={}]) | Stretch the drawable to the right of the parent area.
stretch_up (d[, args={}]) | Stretch the drawable to the top of the parent area.
stretch_down (d[, args={}]) | Stretch the drawable to the bottom of the parent area.
maximize ([d=client.focus[, args={}]]) | Maximize a drawable horizontally, vertically or both.
maximize_vertically (d[, args={}]) | Vetically maximize the drawable in the parent area.
maximize_horizontally (d[, args={}]) | Horizontally maximize the drawable in the parent area.
scale ([d=client.focus[, args={}]]) | Scale the drawable by either a relative or absolute percent.
next_to (d, args) | Move a drawable to a relative position next to another one.
restore ([d=client.focus[, args={}]]) | Restore the geometry.

## Functions

Methods

closest_corner ([d=client.focus[, args={}]])

  Move a drawable to the closest corner of the parent geometry (such as the screen).

  Valid arguments include the common ones and:

  - include_sides: Also include the left, right, top and bottom positions

  Usage example output:

      Closest corner: top_left

  - d drawable A drawable (like client, mouse or wibox) (default client.focus)
  - args table The arguments (default {})

  ### Returns:

  1. table The new geometry
  2. string The corner name

  ### Usage:

      -- Move the mouse to the closest corner of the focused client
      wful.placement.closest_corner(mouse, {include_sides=true, parent=c})
      -- It is possible to emulate the mouse API to get the closest corner of
      -- random area
      ocal _, corner = awful.placement.closest_corner(
         {coords=function() return {x = 100, y=100} end},
         {include_sides = true, bounding_rect = {x=0, y=0, width=200, height=200}}

      rint('Closest corner:', corner)

no_offscreen (c[, screen=client's screen])

  Place the client so no part of it will be outside the screen (workarea).

  Usage example output:

      Before: x=-30, y=-30, width=100, height=100
      After:  x=10, y=10, width=100, height=100

  - c client.object The client.
  - screen integer The screen. (default client's screen)

  ### Returns:

  table The new client geometry.

  ### Usage:

      awful.placement.no_offscreen(c)--, {honor_workarea=true, margins=40})

no_overlap (c)
  Place the client where there's place available with minimum overlap.

  - c The client.

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.no_overlap(client.focus)
      local x,y = screen[4].geometry.x, screen[4].geometry.y

under_mouse (d[, args={}])
  Place the client under the mouse.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.under_mouse(client.focus)

next_to_mouse (d[, args={}])
  Place the client next to the mouse.

  It will place `c` next to the mouse pointer, trying the following positions in this order: right, left, above and below.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.next_to_mouse(client.focus)

resize_to_mouse (d[, args={}])
  Resize the drawable to the cursor.

  Valid args:

  - axis: The axis (vertical or horizontal). If none is specified, then the drawable will be resized on both axis.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry
align (d[, args={}])
  Move the drawable (client or wibox) `d` to a screen position or side.

  Supported args.positions are:

  - top_left
  - top_right
  - bottom_left
  - bottom_right
  - left
  - right
  - top
  - bottom
  - centered
  - center_vertical
  - center_horizontal

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry
top_left (d[, args={}])
  Align a client to the top left of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.top_left(client.focus)

top_right (d[, args={}])
  Align a client to the top right of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.top_right(client.focus)

bottom_left (d[, args={}])
  Align a client to the bottom left of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom_left(client.focus)

bottom_right (d[, args={}])
  Align a client to the bottom right of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom_right(client.focus)

left (d[, args={}])
  Align a client to the left of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.left(client.focus)

right (d[, args={}])
  Align a client to the right of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.right(client.focus)

top (d[, args={}])
  Align a client to the top of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.top(client.focus)
      assert(c.x == screen[1].geometry.width/2-40/2-c.border_width)

bottom (d[, args={}])
  Align a client to the bottom of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom(client.focus)

centered (d[, args={}])
  Align a client to the center of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.centered(client.focus)

center_vertical (d[, args={}])
  Align a client to the vertical center of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Usage:

      awful.placement.center_vertical(client.focus)

center_horizontal (d[, args={}])
  Align a client to the horizontal center left of the parent area.

  - d drawable A drawable (like client, mouse or wibox)
  - args table Other arguments') (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.center_horizontal(client.focus)

stretch ([d=client.focus[, args={}]])
  Stretch a drawable in a specific direction. Valid args:
  - direction: The stretch direction (left, right, up, down) or a table with multiple directions.

  - d drawable A drawable (like client or wibox) (default client.focus)
  - args table The arguments (default {})

  ### Returns:

  table The new geometry
stretch_left (d[, args={}])
  Stretch the drawable to the left of the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_left(client.focus)

stretch_right (d[, args={}])
  Stretch the drawable to the right of the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_right(client.focus)

stretch_up (d[, args={}])
  Stretch the drawable to the top of the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_up(client.focus)

stretch_down (d[, args={}])
  Stretch the drawable to the bottom of the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments (default {})

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_down(client.focus)

maximize ([d=client.focus[, args={}]])
  Maximize a drawable horizontally, vertically or both. Valid args:
  - axis:The axis (vertical or horizontal). If none is specified, then the drawable will be maximized on both axis.

  - d drawable A drawable (like client or wibox) (default client.focus)
  - args table The arguments (default {})

  ### Returns:

  table The new geometry
maximize_vertically (d[, args={}])
  Vetically maximize the drawable in the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments') (default {})

  ### Usage:

      placement.maximize_vertically(c)

maximize_horizontally (d[, args={}])
  Horizontally maximize the drawable in the parent area.

  - d drawable A drawable (like client or wibox)
  - args table Other arguments') (default {})

  ### Usage:

      placement.maximize_horizontally(c)

scale ([d=client.focus[, args={}]])
  Scale the drawable by either a relative or absolute percent.

  Valid args:

  to_percent : A number between 0 and 1. It represent a percent related to the parent geometry. by_percent : A number between 0 and 1. It represent a percent related to the current size. direction: Nothing or "left", "right", "up", "down".

  - d drawable A drawable (like client or wibox) (default client.focus)
  - args table The arguments (default {})

  ### Returns:

  table The new geometry
next_to (d, args)
  Move a drawable to a relative position next to another one.

  The `args.preferred_positions` look like this:

      {"top", "right", "left", "bottom"}

  In that case, if there is room on the top of the geomtry, then it will have priority, followed by all the others, in order.

  - d drawable A wibox or client
  - args
    - mode string The mode
    - preferred_positions string The preferred positions (in order)
    - geometry string A geometry inside the other drawable

  ### Returns:

  1. table The new geometry
  2. string The choosen position
  3. string The choosen direction
restore ([d=client.focus[, args={}]])
  Restore the geometry.
  - d drawable A drawable (like client or wibox) (default client.focus)
  - args table The arguments (default {})

  ### Returns:

  boolean If the geometry was restored

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18