# 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 connectforeach_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

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.
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.
awful.screen.disconnect_for_each_screen (func)
  Undo the effect of connectforeach_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:

  - client.struts
  - wibox.struts
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
  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:

  - all_clients
  - hidden_clients
  - client.get
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:

  - clients
  - all_clients
  - client.get
screen.all_clients
  Get all clients assigned to the screen.

  ### Type:

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

  ### See also:

  - clients
  - hidden_clients
  - client.get
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` 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:

  - tag.selected
  - client.to_selected_tags
screen.selected_tag
  The first selected tag.

  ### Type:

  - table

  ### See also:

  - tag.selected
  - selected_tags

## 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:

  screen.get_square_distance
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:

  padding

## 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. (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-01-20 01:17:18