# 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](https://en.wikipedia.org/wiki/Visitor_pattern) * 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
- Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>,Julien Danjou <julien@danjou.info>
  (Full contributors list available on our github project)

## Static module functions

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

## Static module functions

🔗 awful.placement.closest_corner (d, args) -> (table, string)
  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

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d | Optional | drawable | A drawable (like client, mouse or wibox) | `client.focus`
  args | Optional | table | The arguments | `{}`

  ### Returns:

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

  ### Usage:

      -- Move the mouse to the closest corner of the focused client
      awful.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
      local _, 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}}
      )
      print("Closest corner:", corner)

🔗 awful.placement.no_offscreen (c, args) -> table
  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=50, y=50, width=100, height=100

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | The client. | Not applicable
  args | Optional | table | The arguments | `{}`
  screen | Optional | integer | The screen. | `client's screen`

  ### Returns:

  table The new client geometry.

  ### Usage:

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

🔗 awful.placement.no_overlap (c, args) -> table
  Place the client where there's place available with minimum overlap.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  |  | The client. | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

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

🔗 awful.placement.under_mouse (d, args) -> table
  Place the client under the mouse.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.under_mouse(client.focus)

🔗 awful.placement.next_to_mouse (d, args) -> table
  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.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.next_to_mouse(client.focus)

🔗 awful.placement.resize_to_mouse (d, args) -> table
  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.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry
🔗 awful.placement.align (d, args) -> table
  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

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry
🔗 awful.placement.top_left (d, args) -> table
  Align a client to the top left of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.top_left(client.focus)

🔗 awful.placement.top_right (d, args) -> table
  Align a client to the top right of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.top_right(client.focus)

🔗 awful.placement.bottom_left (d, args) -> table
  Align a client to the bottom left of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom_left(client.focus)

🔗 awful.placement.bottom_right (d, args) -> table
  Align a client to the bottom right of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom_right(client.focus)

🔗 awful.placement.left (d, args) -> table
  Align a client to the left of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.left(client.focus)

🔗 awful.placement.right (d, args) -> table
  Align a client to the right of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.right(client.focus)

🔗 awful.placement.top (d, args) -> table
  Align a client to the top of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

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

🔗 awful.placement.bottom (d, args) -> table
  Align a client to the bottom of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.bottom(client.focus)

🔗 awful.placement.centered (d, args) -> table
  Align a client to the center of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.centered(client.focus)

🔗 awful.placement.center_vertical (d, args) -> table
  Align a client to the vertical center of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.center_vertical(client.focus)

🔗 awful.placement.center_horizontal (d, args) -> table
  Align a client to the horizontal center left of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      awful.placement.center_horizontal(client.focus)

🔗 awful.placement.stretch (d, args) -> table
  Stretch a drawable in a specific direction. Valid args:

  * **direction**: The stretch direction (*left*, *right*, *up*, *down*) or a table with multiple directions.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d | Optional | drawable | A drawable (like client or wibox) | `client.focus`
  args | Optional | table | The arguments | `{}`

  ### Returns:

  table The new geometry
🔗 awful.placement.stretch_left (d, args) -> table
  Stretch the drawable to the left of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_left(client.focus)

🔗 awful.placement.stretch_right (d, args) -> table
  Stretch the drawable to the right of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_right(client.focus)

🔗 awful.placement.stretch_up (d, args) -> table
  Stretch the drawable to the top of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_up(client.focus)

🔗 awful.placement.stretch_down (d, args) -> table
  Stretch the drawable to the bottom of the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.stretch_down(client.focus)

🔗 awful.placement.maximize (d, args) -> table
  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.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d | Optional | drawable | A drawable (like client or wibox) | `client.focus`
  args | Optional | table | The arguments | `{}`

  ### Returns:

  table The new geometry
🔗 awful.placement.maximize_vertically (d, args) -> table
  Vetically maximize the drawable in the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.maximize_vertically(c)

🔗 awful.placement.maximize_horizontally (d, args) -> table
  Horizontally maximize the drawable in the parent area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client or wibox) | Not applicable
  args | Optional | table | Other arguments") | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      placement.maximize_horizontally(c)

🔗 awful.placement.scale (d, args) -> table
  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".

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d | Optional | drawable | A drawable (like client or wibox) | `client.focus`
  args | Optional | table | The arguments | `{}`

  ### Returns:

  table The new geometry
🔗 awful.placement.next_to (d, args) -> (table, string, string)
  Move a drawable to a relative position next to another one.

  This placement function offers two additional settings to align the drawable alongside the parent geometry. The first one, the position, sets the side relative to the parent. The second one, the anchor, set the alignment within the side selected by the `preferred_positions`. Both settings are tables of priorities. The first available slot will be used. If there isn't enough space, then it will fallback to the next until it is possible to fit the drawable. This is meant to avoid going offscreen.

  The `args.preferred_positions` look like this:

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

  The `args.preferred_anchors` are:

  * "front": The closest to the origin (0,0) * "middle": Centered aligned with the parent * "back": The opposite side compared to `front`

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

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  d |  | drawable | A wibox or client
  args |  | table |
  mode |  | string | The mode
  preferred_positions |  | string or table | The preferred positions (in order)
  preferred_anchors |  | string or table | The preferred anchor(s) (in order)
  geometry |  | string | A geometry inside the other drawable

  ### Returns:

  1. table The new geometry
  2. string The chosen position ("left", "right", "top" or "bottom")
  3. string The chosen anchor ("front", "middle" or "back")

  ### Usage:

      for _, pos in ipairs{"left", "right", "top", "bottom"} do
          for _, anchor in ipairs{"front", "middle", "back"} do
              awful.placement.next_to(
                  client.focus,
                  {
                      preferred_positions = pos,
                      preferred_anchors   = anchor,
                      geometry            = parent_client,
                  }
              )
          end
      end

      The args.mode parameters allows to control from which next_to takes its
      source object from. The valid values are:

      * geometry: Next to this geometry, args.geometry has to be set.
      * cursor: Next to the mouse.
      * cursor_inside
      * geometry_inside

🔗 awful.placement.restore (d, args) -> boolean
  Restore the geometry.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d | Optional | drawable | A drawable (like client or wibox) | `client.focus`
  args | Optional | table | The arguments | `{}`

  ### Returns:

  boolean If the geometry was restored
🔗 awful.placement.skip_fullscreen (d, args) -> table
  Skip all preceding results of placement pipeline for fullscreen clients.

  **Usage example output**:

  no_offscreen: Before: x=0, y=0, width=320, height=240 After: x=10, y=10, width=320, height=240 no_offscreen + skip_fullscreen: Before: x=0, y=0, width=320, height=240 After: x=0, y=0, width=320, height=240

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  d |  | drawable | A drawable (like client, mouse or wibox) | Not applicable
  args | Optional | table | Other arguments | `{}`

  ### Returns:

  table The new geometry

  ### Usage:

      -- using just no_offscreen with honor_workarea:
      awful.placement.no_offscreen(c, {honor_workarea=true, })
      -- using no_offscreen + skip_fullscreen:
      local f = (awful.placement.no_offscreen + awful.placement.skip_fullscreen)
      f(c, {honor_workarea=true, })

generated by LDoc 1.5.0