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:

Usage example

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

Usage example

-- 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=client.focus[, 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={}]) 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=client.focus[, 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=client.focus[, args={}]]) -> table Maximize a drawable horizontally, vertically or both.
awful.placement.maximize_vertically (d[, args={}]) Vetically maximize the drawable in the parent area.
awful.placement.maximize_horizontally (d[, args={}]) Horizontally maximize the drawable in the parent area.
awful.placement.scale ([d=client.focus[, 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=client.focus[, 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=client.focus[, 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

Usage example output:

Parameters:

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

Usage example output:

Parameters:

  • c client The client.
  • args The arguments
    • 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})
awful.placement.no_overlap (c[, args={}]) -> table
Place the client where there's place available with minimum overlap.

Usage example

Parameters:

  • c The client.
  • args table Other arguments (default {})

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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

Usage example

Parameters:

Returns:

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

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

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.

Usage example

Parameters:

Returns:

    table The new geometry

Usage:

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

Usage example

Parameters:

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.

Usage example

Parameters:

Returns:

    table The new geometry

Usage:

    awful.placement.center_horizontal(client.focus)
awful.placement.stretch ([d=client.focus[, 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.

Usage example

Parameters:

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

Returns:

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

Usage example

Parameters:

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

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.

Usage example

Parameters:

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

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.

Usage example

Parameters:

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

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.

Usage example

Parameters:

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

Returns:

    table The new geometry

Usage:

    placement.stretch_down(client.focus)
awful.placement.maximize ([d=client.focus[, 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.

Usage example

Parameters:

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

Returns:

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

Usage example

Parameters:

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

Usage:

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

Usage example

Parameters:

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

Usage:

    placement.maximize_horizontally(c)
awful.placement.scale ([d=client.focus[, 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:

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

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.

Usage example

Parameters:

  • d drawable A wibox or client
  • args
    • 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=client.focus[, args={}]]) -> boolean
Restore the geometry.

Parameters:

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

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

Usage example output:

Parameters:

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.4.6 Last updated 2021-11-13 00:35:50