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:

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