Class screen

awesome screen API

Screen objects can be added and removed over time.

To get a callback for all current and future screens, use awful.screen.connect_for_each_screen:

awful.screen.connect_for_each_screen(function(s)
    -- do something
end)

It is also possible loop over all current screens using:

for s in screen do
    -- do something
end

Most basic Awesome objects also have a screen property, see mouse.screen client.screen, wibox.screen and tag.screen.

Furthermore to the classes described here, one can also use signals as described in signals.

Info:

Functions

awful.screen.getbycoord (x, y) Return the screen index corresponding to the given (pixel) coordinates.
awful.screen.focus (_screen) Move the focus to a screen.
awful.screen.focus_bydirection (dir, _screen) Move the focus to a screen in a specific direction.
awful.screen.focus_relative (offset) Move the focus to a screen relative to the current one,
awful.screen.focused ([args]) Get the focused screen.
client:get_clients ([stacked=true]) Get the list of visible clients for the screen.
client:get_all_clients ([stacked=true]) Get all clients assigned to the screen.
client:get_tiled_clients ([stacked=true]) Get tiled clients for the screen.
awful.screen.connect_for_each_screen (func) Call a function for each existing and created-in-the-future screen.
awful.screen.disconnect_for_each_screen (func) Undo the effect of connect_for_each_screen.

Object properties

screen.geometry The screen coordinates.
screen.index The screen number.
screen.outputs If RANDR information is available, a list of outputs for this screen and their size in mm.
screen.workarea The screen workarea.
screen.padding The screen padding.
screen.clients The list of visible clients for the screen.
screen.hidden_clients Get the list of clients assigned to the screen but not currently visible.
screen.all_clients All clients assigned to the screen.
screen.tiled_clients Tiled clients for the screen.
screen.tags A list of all tags on the screen.
screen.selected_tags A list of all selected tags on the screen.
screen.selected_tag The first selected tag.

Signals

.primary_changed
.added This signal is emitted when a new screen is added to the current setup.
screen.removed This signal is emitted when a screen is removed from the setup.
.list This signal is emitted when the list of available screens changes.
.swapped When 2 screens are swapped
tag::history::update When the tag history changed.

Deprecated functions

awful.screen.getdistance_sq Get the square distance between a screen and a point.
awful.screen.padding Get or set the screen padding.

Fields

screen.primary The primary screen.
awful.screen.default_focused_args The defaults arguments for awful.screen.focused.

Methods

screen:instances () Get the number of instances.
screen:screen () Iterate over screens.
screen:count () Get the number of screens.
screen:fake_add (x, y, width, height) Add a fake screen.
screen:fake_remove () Remove a screen.
screen:fake_resize (x, y, width, height) Fake-resize a screen
screen:swap (s) Swap a screen with another one in global screen list.
screen:get_square_distance (x, y) Get the square distance between a screen and a point.
screen:get_next_in_direction (self, dir) Get the next screen in a specific direction.
screen:preferred (c) Get the preferred screen in the context of a client.
screen:get_bounding_geometry ([args={}]) Get a placement bounding geometry.


Functions

Methods
awful.screen.getbycoord (x, y)
Return the screen index corresponding to the given (pixel) coordinates.

The number returned can be used as an index into the global screen table/object.

  • x number The x coordinate
  • y number The y coordinate

Returns:

    optional number The screen index
awful.screen.focus (_screen)
Move the focus to a screen.

This moves the mouse pointer to the last known position on the new screen, or keeps its position relative to the current focused screen.

  • _screen screen Screen number (defaults / falls back to mouse.screen).
awful.screen.focus_bydirection (dir, _screen)
Move the focus to a screen in a specific direction.

This moves the mouse pointer to the last known position on the new screen, or keeps its position relative to the current focused screen.

  • dir The direction, can be either “up”, “down”, “left” or “right”.
  • _screen Screen.
awful.screen.focus_relative (offset)
Move the focus to a screen relative to the current one, This moves the mouse pointer to the last known position on the new screen, or keeps its position relative to the current focused screen.
  • offset int Value to add to the current focused screen index. 1 to focus the next one, -1 to focus the previous one.
awful.screen.focused ([args])
Get the focused screen.

It is possible to set awful.screen.default_focused_args to override the default settings.

  • args
    • client boolean Use the client screen instead of the mouse screen. (default false)
    • mouse boolean Use the mouse screen (default true)

Returns:

    optional screen The focused screen object, or nil in case no screen is present currently.
client:get_clients ([stacked=true])
Get the list of visible clients for the screen.

This is used by screen.clients internally (with stacked=true).

  • stacked boolean Use stacking order? (top to bottom) (default true)

Returns:

    table The clients list.
client:get_all_clients ([stacked=true])
Get all clients assigned to the screen.

This is used by all_clients internally (with stacked=true).

  • stacked boolean Use stacking order? (top to bottom) (default true)

Returns:

    table The clients list.
client:get_tiled_clients ([stacked=true])
Get tiled clients for the screen.

This is used by tiles_clients internally (with stacked=true).

  • stacked boolean Use stacking order? (top to bottom) (default true)

Returns:

    table The clients list.
awful.screen.connect_for_each_screen (func)
Call a function for each existing and created-in-the-future screen.
  • func The function to call.
awful.screen.disconnect_for_each_screen (func)
Undo the effect of connect_for_each_screen.
  • func function The function that should no longer be called.

Object properties

screen.geometry
The screen coordinates.

Signal:

  • property::geometry

Immutable: true

Type:

  • table
    • x integer The horizontal position
    • y integer The vertical position
    • width integer The width
    • height integer The height
screen.index
The screen number.

An integer greater than 1 and smaller than screen.count(). Please note that the screen order isn’t always mirroring the screen logical position.

Immutable: true

Type:

  • integer
screen.outputs
If RANDR information is available, a list of outputs for this screen and their size in mm.

Please note that the table content may vary.

Signal:

  • property::outputs

Immutable: true

Type:

  • table
    • name table A table with the screen name as key (like eDP1 on a laptop)
    • name.mm_width integer The screen physical width
    • name.mm_height integer The screen physical height
screen.workarea

The screen workarea.

The workarea is a subsection of the screen where clients can be placed. It usually excludes the toolbars (see awful.wibar) and dockable clients (see client.dockable) like WindowMaker DockAPP.

It can be modified be altering the wibox or client struts.

Signal:

  • property::workarea

Type:

  • table
    • x integer The horizontal position
    • y integer The vertical position
    • width integer The width
    • height integer The height

See also:

screen.padding

The screen padding.

This adds a “buffer” section on each side of the screen.

Signal:

  • property::padding

Type:

  • table
    • left integer The padding on the left.
    • right integer The padding on the right.
    • top integer The padding on the top.
    • bottom integer The padding on the bottom.
screen.clients
The list of visible clients for the screen.

Minimized and unmanaged clients are not included in this list as they are technically not on the screen.

The clients on tags that are currently not visible are not part of this list.

Clients are returned using the stacking order (from top to bottom). See get_clients if you want them in the order used in the tasklist by default.

Type:

  • table The clients list, ordered from top to bottom.

See also:

screen.hidden_clients
Get the list of clients assigned to the screen but not currently visible.

This includes minimized clients and clients on hidden tags.

Type:

  • table The clients list, ordered from top to bottom.

See also:

screen.all_clients
All clients assigned to the screen.

Type:

  • table The clients list, ordered from top to bottom.

See also:

screen.tiled_clients

Tiled clients for the screen.

Same as clients, but excluding:

  • fullscreen clients
  • maximized clients
  • floating clients

Type:

  • table The clients list, ordered from top to bottom.
screen.tags
A list of all tags on the screen.

This property is read only, use tag.screen, awful.tag.add, awful.tag.new or t:delete() to alter this list.

Type:

  • table
screen.selected_tags
A list of all selected tags on the screen.

Type:

  • table

See also:

screen.selected_tag
The first selected tag.

Type:

  • table

See also:

Signals

.primary_changed
.added
This signal is emitted when a new screen is added to the current setup.
screen.removed
This signal is emitted when a screen is removed from the setup.
.list
This signal is emitted when the list of available screens changes.
.swapped
When 2 screens are swapped

Arguments:

  • screen screen The other screen
  • is_source boolean If self is the source or the destination of the swap
tag::history::update
When the tag history changed.

Deprecated functions

awful.screen.getdistance_sq
Get the square distance between a screen and a point.

param:

  • s Screen
  • x X coordinate of point
  • y Y coordinate of point

See also:

awful.screen.padding
Get or set the screen padding.

param:

  • _screen The screen object to change the padding on
  • padding The padding, a table with ‘top’, ‘left’, ‘right’ and/or ‘bottom’ or a number value to apply set the same padding on all sides. Can be nil if you only want to retrieve padding (default nil)

See also:

Fields

screen.primary
The primary screen.
awful.screen.default_focused_args
The defaults arguments for awful.screen.focused.

Methods

screen:instances ()
Get the number of instances.

Returns:

    The number of screen objects alive.
screen:screen ()
Iterate over screens.

Usage:

    for s in screen do
        print("Oh, wow, we have screen " .. tostring(s))
    end
screen:count ()
Get the number of screens.

Returns:

    The screen count, at least 1.
screen:fake_add (x, y, width, height)
Add a fake screen.

To vertically split the first screen in 2 equal parts, use:

local geo = screen[1].geometry
local new_width = math.ceil(geo.width/2)
local new_width2 = geo.width - new_width
screen[1]:fake_resize(geo.x, geo.y, new_width, geo.height)
screen.fake_add(geo.x + new_width, geo.y, new_width2, geo.height)

Both virtual screens will have their own taglist and wibars.

  • x integer X-coordinate for screen.
  • y integer Y-coordinate for screen.
  • width integer width for screen.
  • height integer height for screen.

Returns:

    The new screen.
screen:fake_remove ()
Remove a screen.
screen:fake_resize (x, y, width, height)
Fake-resize a screen
  • x integer The new X-coordinate for screen.
  • y integer The new Y-coordinate for screen.
  • width integer The new width for screen.
  • height integer The new height for screen.
screen:swap (s)
Swap a screen with another one in global screen list.
screen:get_square_distance (x, y)
Get the square distance between a screen and a point.
  • x number X coordinate of point
  • y number Y coordinate of point

Returns:

    number The squared distance of the screen to the provided point.
screen:get_next_in_direction (self, dir)
Get the next screen in a specific direction.

This gets the next screen relative to this one in the specified direction.

  • self Screen.
  • dir The direction, can be either “up”, “down”, “left” or “right”.
screen:preferred (c)
Get the preferred screen in the context of a client.

This is exactly the same as awful.screen.focused except that it avoids clients being moved when Awesome is restarted. This is used in the default rc.lua to ensure clients get assigned to the focused screen by default.

Returns:

    screen The preferred screen.
screen:get_bounding_geometry ([args={}])
Get a placement bounding geometry.

This method computes the different variants of the “usable” screen geometry.

  • args The arguments
    • honor_padding boolean Whether to honor the screen’s padding. (default false)
    • honor_workarea boolean Whether to honor the screen’s workarea. (default false)
    • margins int or table Apply some margins on the output. This can either be a number or a table with left, right, top and bottom keys. (optional)
    • tag tag Use this tag’s screen. (optional)
    • parent drawable A parent drawable to use as base geometry. (optional)
    • bounding_rect table A bounding rectangle. This parameter is incompatible with honor_workarea. (optional)

Returns:

    table A table with x, y, width and height.

Usage:

    local geo = screen:get_bounding_geometry {
        honor_padding  = true,
        honor_workarea = true,
        margins        = {
             left = 20,
        },
    }
generated by LDoc 1.4.6 Last updated 2017-09-11 12:23:44