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:
- Copyright: 2008-2009 Julien Danjou
- Author: Julien Danjou <julien@danjou.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. |
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 | Get 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 | Get all clients assigned to the screen. |
screen.tiled_clients | Get the list of 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:preferred (c) | Get the preferred screen in the context of a client. |
screen:get_bounding_geometry ([args={}]) | Get a placement bounding geometry. |
Functions
- 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. - args
- awful.screen.connect_for_each_screen (func)
-
Call a function for each existing and created-in-the-future screen.
- func The function to call.
- screen screen The 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
- table
- 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
- name
table
A table with the screen name as key (like
- table
- 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:
- table
- 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.
- table
- screen.clients
-
Get 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.
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
-
Get all clients assigned to the screen.
Type:
- table The clients list, ordered from top to bottom.
See also:
- screen.tiled_clients
-
Get the list of 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
ort: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.
- 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.
- s client.object A screen to swap with.
- 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: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.- c client A client.
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.
- tag tag Use this tag's screen.
- parent drawable A parent drawable to use as base geometry.
- bounding_rect
table
A bounding rectangle. This parameter is
incompatible with
honor_workarea
.
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, }, }
- args The arguments