# Module: `wibox.layout.grid`

Place multiple widgets in multiple rows and columns.

Widgets spanning several columns or rows cannot be included using the declarative system. Instead, create the grid layout and call the add_widget_at method.

local l = wibox.widget { homogeneous = true, spacing = 5, minimum_column_width = 10, minimum_row_height = 10, layout = wibox.layout.grid, } l:add_widget_at(first , 2, 1, 1, 2) l:add_widget_at(second, 3, 1, 1, 2) l:add_widget_at(third , 2, 3, 2, 1) l:add_widget_at(fourth, 4, 1, 1, 1) l:add_widget_at(fifth , 4, 2, 1, 2) l:insert_row(1) l:add_widget_at(lorem, 1, 1, 1, 3)

The same can be done using the declarative syntax:

local lorem = "Lorem ipsum dolor sit amet, consectetur adipiscing " .. "elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." local l = wibox.widget { { text = lorem, row_index = 1, col_index = 1, col_span = 3, widget = generic_widget }, { text = "first", col_span = 2, row_index = 2, col_index = 1, widget = generic_widget }, { text = "third", row_index = 2, col_index = 3, row_span = 2, widget = generic_widget }, { text = "second", row_index = 3, col_index = 1, col_span = 2, widget = generic_widget }, { text = "fourth", row_index = 4, col_index = 1, widget = generic_widget }, { text = "fifth", row_index = 4, col_index = 2, col_span = 2, widget = generic_widget }, homogeneous = true, spacing = 5, border_width = 1, border_color = beautiful.border_color, minimum_column_width = 10, minimum_row_height = 10, layout = wibox.layout.grid, }

When `col_index` and `row_index` are not provided, the widgets are automatically added next to each other spanning only one cell:

local l = wibox.widget { generic_widget("first"), generic_widget("second"), generic_widget("third"), generic_widget("fourth"), generic_widget("fifth"), column_count = 2, spacing = 5, minimum_column_width = 10, minimum_row_height = 10, layout = wibox.layout.grid, }

### Usage:

    wibox.widget {
        generic_widget( "first"  ),
        generic_widget( "second" ),
        generic_widget( "third"  ),
        generic_widget( "fourth" ),
        column_count = 2,
        row_count    = 2,
        homogeneous  = true,
        expand       = true,
        layout       = wibox.layout.grid
    }

### Class Hierarchy

- gears.object
- - wibox.widget.base
  - - wibox.layout.grid

### Info:

- Copyright: 2017 getzze
- Originally authored by: getzze
  (Full contributors list available on our github project)

## Constructors

wibox.layout.grid (orientation) | Return a new grid layout. |
wibox.layout.grid.horizontal (forced_num_rows, ...) | Return a new horizontal grid layout. |
wibox.layout.grid.vertical (forced_num_cols, ...) | Return a new vertical grid layout. |

## Object properties

orientation | string | Set the preferred orientation of the grid layout. |
superpose | boolean | Allow to superpose widgets in the same cell. |
minimum_column_width | number | Set the minimum size for the columns. |
minimum_row_height | number | Set the minimum size for the rows. |
spacing | number or table | The spacing between rows and columns. |
expand | boolean or table | Controls if the columns/rows are expanded to use all the available space. |
homogeneous | boolean or table | Controls if the columns/rows all have the same size or if the size depends on the content. |
row_count | integer | The number of rows. |
column_count | integer | The number of columns. |
border_width | integer or table | The border width. |
border_color | color or table | The border color for the table outer border. |
children | table | Get or set the children elements. | Inherited from wibox.widget.base
all_children | table | Get all direct and indirect children widgets. | Inherited from wibox.widget.base
forced_height | number or nil | Force a widget height. | Inherited from wibox.widget.base
forced_width | number or nil | Force a widget width. | Inherited from wibox.widget.base
opacity | number | The widget opacity (transparency). | Inherited from wibox.widget.base
visible | boolean | The widget visibility. | Inherited from wibox.widget.base
buttons | table | The widget buttons. | Inherited from wibox.widget.base

## Deprecated object properties

forced_num_rows | number or nil | Force the number of rows of the layout. | Deprecated
forced_num_cols | number or nil | Force the number of columns of the layout. | Deprecated
min_cols_size | number | Set the minimum size for the columns. | Deprecated
min_rows_size | number | Set the minimum size for the rows. | Deprecated
horizontal_spacing | number | The spacing between columns. | Deprecated
vertical_spacing | number | The spacing between rows. | Deprecated
horizontal_expand | boolean | Controls if the columns are expanded to use all the available width. | Deprecated
vertical_expand | boolean | Controls if the rows are expanded to use all the available height. | Deprecated
horizontal_homogeneous | boolean | Controls if the columns all have the same width or if the width of each column depends on the content. | Deprecated
vertical_homogeneous | boolean | Controls if the rows all have the same height or if the height of each row depends on the content. | Deprecated

## Deprecated object methods

:get_dimension () -> number,number | Get the number of rows and columns occupied by the widgets in the grid. | Deprecated
:add_widget_at (child, row, col, row_span, col_span) -> boolean | Add a widget to the grid layout at specific coordinate. | Deprecated

## Object methods

:get_next_empty (hint_row, hint_column) -> () | Find the next available cell to insert a widget. |
:add (...) | Add some widgets to the given grid layout. |
:remove (...) -> boolean | Remove one or more widgets from the layout. |
:remove_widgets_at (row, col, row_span, col_span) -> boolean | Remove widgets at the coordinates. |
:get_widget_position (widget) -> table | Return the coordinates of the widget. |
:get_widgets_at (row, col, row_span, col_span) -> table | Return the widgets at the coordinates. |
:replace_widget (old, new) -> boolean | Replace old widget by new widget, spanning the same columns and rows. |
:insert_column (index) -> number | Insert column at index. |
:extend_column (index) -> number | Extend column at index. |
:remove_column (index) -> number | Remove column at index. |
:insert_row (index) -> number | Insert row at index. |
:extend_row (index) -> number | Extend row at index. |
:remove_row (index) -> number | Remove row at index. |
:add_row_border (index, height, args) | Add row border. |
:add_column_border (index, height, args) | Add column border. |
:reset () | Reset the grid layout. |
:set (index, widget2) -> boolean | Set a widget at a specific index, replacing the current one. |
:replace_widget (widget, widget2, recursive) -> boolean | Replace the first instance of `widget` in the layout with `widget2`. |
:swap (index1, index2) -> boolean | Swap 2 widgets in a layout. |
:swap_widgets (widget1, widget2, recursive) -> boolean | Swap 2 widgets in a layout. |
:reset () | Reset the layout. |
:add_button (button) | Add a new awful.button to this widget. | Inherited from wibox.widget.base
:emit_signal_recursive (signal_name, ...) | Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. | Inherited from wibox.widget.base
:index (widget, recursive, ...) -> (number, widget, table) | Get the index of a widget. | Inherited from wibox.widget.base
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object
:disconnect_signal (name, func) | Disconnect from a signal. | Inherited from gears.object
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object

## Signals

widget::reset | When the layout is reset. |
widget::layout_changed | When the layout (size) change. | Inherited from wibox.widget.base
widget::redraw_needed | When the widget content changed. | Inherited from wibox.widget.base
button::press | When a mouse button is pressed over the widget. | Inherited from wibox.widget.base
button::release | When a mouse button is released over the widget. | Inherited from wibox.widget.base
mouse::enter | When the mouse enter a widget. | Inherited from wibox.widget.base
mouse::leave | When the mouse leave a widget. | Inherited from wibox.widget.base

## Tables

wibox.layout.grid.position | Child widget position. |

## Constructors

🔗 wibox.layout.grid (orientation)
  Return a new grid layout.

  A grid layout sets widgets in a grids of custom number of rows and columns.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  orientation | Optional | string | The preferred grid extension direction. | `"y"`

🔗 wibox.layout.grid.horizontal (forced_num_rows, ...)
  Return a new horizontal grid layout.

  Each new widget is positioned below the last widget on the same column up to forced_num_rows. Then the next column is filled, creating it if it doesn't exist.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  forced_num_rows |  | number or nil | Forced number of rows (`nil` for automatic).
  ... |  | widget | Widgets that should be added to the layout.

🔗 wibox.layout.grid.vertical (forced_num_cols, ...)
  Return a new vertical grid layout.

  Each new widget is positioned left of the last widget on the same row up to forced_num_cols. Then the next row is filled, creating it if it doesn't exist.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  forced_num_cols |  | number or nil | Forced number of columns (`nil` for automatic).
  ... |  | widget | Widgets that should be added to the layout.

## Object properties

🔗 orientation string
  Set the preferred orientation of the grid layout.

  When calling get_next_empty, empty cells are browsed differently.

  ### Constraints:

  Default value | : `"vertical"`
  Valid values: | : Preferred orientation.
  `"horizontal"` | : The grid can be extended horizontally. The current column is filled first; if no empty cell is found up to `forced_num_rows`, the next column is filled, creating it if it does not exist.
  `"vertical"` | : The grid can be extended vertically. The current row is filled first; if no empty cell is found up to `forced_num_cols`, the next row is filled, creating it if it does not exist.

🔗 superpose boolean
  Allow to superpose widgets in the same cell. If false, check before adding a new widget if it will superpose with another widget and prevent from adding it.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

🔗 minimum_column_width number
  Set the minimum size for the columns.

  ### Constraints:

  Default value | : `0`
  Unit | : pixel
  Negative allowed | : false
  Valid values | : Minimum size of the columns.

  ### See also:

  minimum_row_height | Set the minimum size for the rows. | object properties

🔗 minimum_row_height number
  Set the minimum size for the rows.

  ### Constraints:

  Default value | : `0`
  Unit | : pixel
  Negative allowed | : false
  Valid values | : Minimum size of the rows.

  ### See also:

  min_cols_size | Set the minimum size for the columns. | deprecated object properties

🔗 spacing number or table
  The spacing between rows and columns.

  Get the value horizontal_spacing or vertical_spacing defined by the preferred orientation.

  When a border is present, the spacing is applied on both side of the border, thus is twice as large:

  for _, width in ipairs { 0, 1, 2, 4, 10 } do local w = wibox.widget { generic_widget( "first" ), generic_widget( "second" ), generic_widget( "third" ), generic_widget( "fourth" ), column_count = 2, row_count = 2, homogeneous = true, spacing = width, border_width = 1, border_color = "red", layout = wibox.layout.grid, } end

  ### Constraints:

  Default value | : `0`
  Type description:
  number | : The same value for the `"vertical"` and `"horizontal"` aspects.
  table: | : Different values for the `"vertical"` and `"horizontal"` aspects.
  vertical (number) | : The vertical spacing.
  horizontal (number) | : The horizontal spacing.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  vertical_spacing | The spacing between rows. | deprecated object properties
  horizontal_spacing | The spacing between columns. | deprecated object properties

🔗 expand boolean or table
  Controls if the columns/rows are expanded to use all the available space.

  Get the value horizontal_expand or vertical_expand defined by the preferred orientation.

  ### Constraints:

  Default value | : `false`
  Type description:
  number | : The same value for the `"vertical"` and `"horizontal"` aspects.
  table: | : Different values for the `"vertical"` and `"horizontal"` aspects.
  vertical (boolean) | : The vertical expand.
  horizontal (boolean) | : The horizontal expand.
  Valid values | : Expand the grid into the available space

  ### See also:

  horizontal_expand | Controls if the columns are expanded to use all the available width. | deprecated object properties
  vertical_expand | Controls if the rows are expanded to use all the available height. | deprecated object properties

🔗 homogeneous boolean or table
  Controls if the columns/rows all have the same size or if the size depends on the content. Set both horizontal_homogeneous and vertical_homogeneous to the same value. Get the value horizontal_homogeneous or vertical_homogeneous defined by the preferred orientation.

  ### Constraints:

  Default value | : `true`
  Type description:
  number | : The same value for the `"vertical"` and `"horizontal"` aspects.
  table: | : Different values for the `"vertical"` and `"horizontal"` aspects.
  vertical (boolean) | : The vertical homogeneous value.
  horizontal (boolean) | : The horizontal homogeneous value.
  Valid values | : All the columns/rows have the same size.

  ### See also:

  vertical_homogeneous | Controls if the rows all have the same height or if the height of each row depends on the content. | deprecated object properties
  horizontal_homogeneous | Controls if the columns all have the same width or if the width of each column depends on the content. | deprecated object properties

🔗 row_count integer
  The number of rows.

  Unless manually set, the value will be automatically determined base on the orientation.

  ### Constraints:

  Default value | : autogenerated
  Negative allowed | : false

  ### See also:

  forced_num_rows | Force the number of rows of the layout. | deprecated object properties

🔗 column_count integer
  The number of columns.

  Unless manually set, the value will be automatically determined base on the orientation.

  ### Constraints:

  Default value | : autogenerated
  Negative allowed | : false

  ### See also:

  forced_num_cols | Force the number of columns of the layout. | deprecated object properties

🔗 border_width integer or table
  The border width.

  for _, expand in ipairs { true, false } do for _, homogeneous in ipairs { true, false } do for _, width in ipairs { 0, 1, 2, 4, 10 } do local w = wibox.widget { generic_widget( "first" ), generic_widget( "second" ), generic_widget( "third" ), generic_widget( "fourth" ), generic_widget( "fifth" ), generic_widget( "sixth" ), column_count = 2, row_count = 2, homogeneous = homogeneous, spacing = 10, border_width = { inner = width, outer = 1.5 * width, }, border_color = "red", expand = expand, forced_height = expand and 200 or nil, layout = wibox.layout.grid, } end end end

  If add_row_border or add_column_border is used, it takes precedence and is drawn on top of the border_color mask. Using both border_width and add_row_border at the same time makes little sense:

  local w = wibox.widget { homogeneous = true, spacing = 0, border_width = 4, border_color = beautiful.border_color, minimum_column_width = 10, minimum_row_height = 10, layout = wibox.layout.grid, } w:add_row_border(1, 40, { color = "red" }) w:add_row_border(2, 5 , { color = "green" , dashes = {5, 3, 10, 3}}) w:add_row_border(3, 10, { color = "blue" , dashes = {5, 3, 10, 3}, dash_offset = 5}) w:add_row_border(4, 30, { color = "orange", dashes = {5, 40}, caps = "round"}) w:add_row_border(5, 10, { color = "yellow"}) w:add_column_border(1, 5, { color = "purple"}) w:add_column_border(2, 10, { color = "cyan"}) w:add_column_border(3, 5, { color = "magenta"}) w:add_column_border(4, 5, { color = "black"}) w:add_column_border(5, 10, { color = "grey"})

  It is also possible to set the inner and outer borders separately:

  for _, width in ipairs { 0, 1, 2, 4, 10 } do local w = wibox.widget { generic_widget( "first" ), generic_widget( "second" ), generic_widget( "third" ), generic_widget( "fourth" ), column_count = 2, row_count = 2, homogeneous = true, spacing = 10, border_width = { inner = width, outer = 10 - width, }, border_color = { inner = gears.color { type = "linear", from = { 0 , 0 }, to = { 100, 100 }, stops = { { 0, "#ff0000" }, { 1, "#ffff00" }, } }, outer = gears.color { type = "linear", from = { 0 , 0 }, to = { 100, 100 }, stops = { { 0, "#0000ff" }, { 1, "#ff0000" }, } }, }, layout = wibox.layout.grid, }

  ### Constraints:

  Default value | : `0`
  Type description:
  integer | : Use the same value for inner and outer borders.
  table: | : Specify a different value for the inner and outer borders.
  inner (integer)
  outer (integer)
  Negative allowed | : false

  ### See also:

  border_color | The border color for the table outer border. | object properties
  add_column_border | Add column border. | object methods
  add_row_border | Add row border. | object methods

🔗 border_color color or table
  The border color for the table outer border.

  ### Constraints:

  Default value | : `0`
  Type description:
  color | : Use the same value for inner and outer borders.
  table: | : Specify a different value for the inner and outer borders.
  inner (color)
  outer (color)

  ### See also:

  border_width | The border width. | object properties

🔗 children table · Inherited from wibox.widget.base
  Get or set the children elements.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of wibox.widget.

  ### See also:

  wibox.widget.base.all_children |  |

🔗 all_children table · Inherited from wibox.widget.base
  Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow if there is a loop in the widgets hierarchy. A hierarchy loop is when a widget, or any of its children, contain (directly or indirectly) itself.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of wibox.widget.

  ### See also:

  wibox.widget.base.children |  |

🔗 forced_height number or nil · Inherited from wibox.widget.base
  Force a widget height.

  ### Constraints:

  Default value | : `nil`
  Type description:
  nil | : Let the layout decide the height. Usually using the widget native height.
  number | : Enforce a number of pixels.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  wibox.widget.base.forced_width |  |

🔗 forced_width number or nil · Inherited from wibox.widget.base
  Force a widget width.

  ### Constraints:

  Default value | : `nil`
  Type description:
  nil | : Let the layout decide the width. Usually using the widget native width.
  number | : Enforce a number of pixels.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  wibox.widget.base.forced_height |  |

🔗 opacity number · Inherited from wibox.widget.base
  The widget opacity (transparency).

  ### Constraints:

  Default value | : `1.0`
  Unit | : A gradient between transparent (`0.0`) and opaque (`1.0`).
  Minimum value | : 0.0
  Maximum value | : 1.0

  ### See also:

  wibox.widget.base.visible |  |

🔗 visible boolean · Inherited from wibox.widget.base
  The widget visibility.

  ### Constraints:

  Default value | : `true`
  Valid values | : `true` or `false`.

  ### See also:

  wibox.widget.base.opacity |  |

🔗 buttons table · Inherited from wibox.widget.base
  The widget buttons.

  The table contains a list of awful.button objects.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of awful.button.

  ### See also:

  awful.button | Create easily new buttons objects ignoring certain modifiers. | module

## Deprecated object properties

🔗 forced_num_rows number or nil
  Force the number of rows of the layout.

  Deprecated, use row_count.

  ### See also:

  forced_num_cols | Force the number of columns of the layout. | deprecated object properties
  row_count | The number of rows. | object properties

🔗 forced_num_cols number or nil
  Force the number of columns of the layout.

  Deprecated, use column_count.

  ### See also:

  forced_num_rows | Force the number of rows of the layout. | deprecated object properties
  column_count | The number of columns. | object properties

🔗 min_cols_size number
  Set the minimum size for the columns.

  Deprecated, use minimum_column_width.

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  min_cols_size | Optional | number | Minimum size of the columns. | `0`

  ### See also:

  minimum_row_height | Set the minimum size for the rows. | object properties

🔗 min_rows_size number
  Set the minimum size for the rows.

  Deprecated, use minimum_row_height.

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  min_rows_size | Optional | number | Minimum size of the rows. | `0`

  ### See also:

  min_cols_size | Set the minimum size for the columns. | deprecated object properties

🔗 horizontal_spacing number
  The spacing between columns.

  Deprecated, use spacing.

  ### See also:

  spacing | The spacing between rows and columns. | object properties
  vertical_spacing | The spacing between rows. | deprecated object properties

🔗 vertical_spacing number
  The spacing between rows.

  Deprecated, use spacing.

  ### See also:

  spacing | The spacing between rows and columns. | object properties
  horizontal_spacing | The spacing between columns. | deprecated object properties

🔗 horizontal_expand boolean
  Controls if the columns are expanded to use all the available width.

  Deprecated, use expand.

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  horizontal_expand | Optional | boolean | Expand the grid into the available space | `false`

  ### See also:

  expand | Controls if the columns/rows are expanded to use all the available space. | object properties
  vertical_expand | Controls if the rows are expanded to use all the available height. | deprecated object properties

🔗 vertical_expand boolean
  Controls if the rows are expanded to use all the available height.

  Deprecated, use expand.

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  vertical_expand | Optional | boolean | Expand the grid into the available space | `false`

  ### See also:

  expand | Controls if the columns/rows are expanded to use all the available space. | object properties
  horizontal_expand | Controls if the columns are expanded to use all the available width. | deprecated object properties

🔗 horizontal_homogeneous boolean
  Controls if the columns all have the same width or if the width of each column depends on the content.

  Deprecated, use homogeneous

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  horizontal_homogeneous | Optional | boolean | All the columns have the same width. | `true`

  ### See also:

  vertical_homogeneous | Controls if the rows all have the same height or if the height of each row depends on the content. | deprecated object properties
  homogeneous | Controls if the columns/rows all have the same size or if the size depends on the content. | object properties

🔗 vertical_homogeneous boolean
  Controls if the rows all have the same height or if the height of each row depends on the content.

  Deprecated, use homogeneous

  ### Type constraints:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  vertical_homogeneous | Optional | boolean | All the rows have the same height. | `true`

  ### See also:

  homogeneous | Controls if the columns/rows all have the same size or if the size depends on the content. | object properties
  horizontal_homogeneous | Controls if the columns all have the same width or if the width of each column depends on the content. | deprecated object properties

## Deprecated object methods

🔗 :get_dimension () -> number,number
  Get the number of rows and columns occupied by the widgets in the grid.

  ### Returns:

  number,number The number of rows and columns

  ### See also:

  row_count | The number of rows. | object properties
  column_count | The number of columns. | object properties

🔗 :add_widget_at (child, row, col, row_span, col_span) -> boolean
  Add a widget to the grid layout at specific coordinate.

  You can now use `:add {row_index = 1, col_index = 1}` instead of this method.

  **Usage example output**:

  l:add_widget_at(new, 1, 4, 1, 1)

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  child |  | wibox.widget | Widget that should be added | Not applicable
  row |  | number | Row number for the top left corner of the widget | Not applicable
  col |  | number | Column number for the top left corner of the widget | Not applicable
  row_span | Optional | number | The number of rows the widget spans. | `1`
  col_span | Optional | number | The number of columns the widget spans. | `1`

  ### Returns:

  boolean index If the operation is successful

## Object methods

🔗 :get_next_empty (hint_row, hint_column) -> ()
  Find the next available cell to insert a widget. The grid is browsed according to the orientation.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  hint_row | Optional | number | The row coordinate of the last occupied cell. | `1`
  hint_column | Optional | number | The column coordinate of the last occupied cell. | `1`

  ### Returns:

  number,number The row,column coordinate of the next empty cell
🔗 :add (...)
  Add some widgets to the given grid layout.

  The widgets are assumed to span one cell.

  If the widgets have a `row_index`, `col_index`, `col_span` or `row_span` property, it will be honored.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  ... |  | wibox.widget | Widgets that should be added (must at least be one)

🔗 :remove (...) -> boolean
  Remove one or more widgets from the layout.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  ... |  |  | Widgets that should be removed (must at least be one)

  ### Returns:

  boolean If the operation is successful
🔗 :remove_widgets_at (row, col, row_span, col_span) -> boolean
  Remove widgets at the coordinates.

  **Usage example output**:

  l:remove_widgets_at(1,1)

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  row |  | number | The row coordinate of the widget to remove | Not applicable
  col |  | number | The column coordinate of the widget to remove | Not applicable
  row_span | Optional | number | The number of rows the area to remove spans. | `1`
  col_span | Optional | number | The number of columns the area to remove spans. | `1`

  ### Returns:

  boolean If the operation is successful (widgets found)
🔗 :get_widget_position (widget) -> table
  Return the coordinates of the widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  widget |  | widget | The widget

  ### Returns:

  table The position table of the coordinates in the grid, with fields `row`, `col`, `row_span` and `col_span`.
🔗 :get_widgets_at (row, col, row_span, col_span) -> table
  Return the widgets at the coordinates.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  row |  | number | The row coordinate of the widget | Not applicable
  col |  | number | The column coordinate of the widget | Not applicable
  row_span | Optional | number | The number of rows to span. | `1`
  col_span | Optional | number | The number of columns to span. | `1`

  ### Returns:

  table The widget(s) found at the specific coordinates, nil if no widgets found
🔗 :replace_widget (old, new) -> boolean
  Replace old widget by new widget, spanning the same columns and rows.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  old |  | widget | The widget to remove
  new |  | widget | The widget to add

  ### Returns:

  boolean If the operation is successful (widget found)
🔗 :insert_column (index) -> number
  Insert column at index.

  **Usage example output**:

  l:insert_column(2)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Insert the new column at index. If `nil`, the column is added at the end.

  ### Returns:

  number The index of the inserted column
🔗 :extend_column (index) -> number
  Extend column at index.

  **Usage example output**:

  l:extend_column(2)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Extend the column at index. If `nil`, the last column is extended.

  ### Returns:

  number The index of the extended column
🔗 :remove_column (index) -> number
  Remove column at index.

  **Usage example output**:

  l:remove_column(2)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Remove column at index. If `nil`, the last column is removed.

  ### Returns:

  number The index of the removed column
🔗 :insert_row (index) -> number
  Insert row at index.

  see insert_column

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Insert the new row at index. If `nil`, the row is added at the end.

  ### Returns:

  number The index of the inserted row
🔗 :extend_row (index) -> number
  Extend row at index.

  see extend_column

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Extend the row at index. If `nil`, the last row is extended.

  ### Returns:

  number The index of the extended row
🔗 :remove_row (index) -> number
  Remove row at index.

  see remove_column

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number or nil | Remove row at index. If `nil`, the last row is removed.

  ### Returns:

  number The index of the removed row
🔗 :add_row_border (index, height, args)
  Add row border.

  This method allows to set the width/color or a specific row rather than use the same values for all the rows.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  index |  | integer | The row index. `1` is the top border (outer) border. | Not applicable
  height | Optional | integer or nil | The border height. If `nil` is passed, then the `border_width.outer` will be user for index `1` and `row_count + 1`, otherwise, `border_width.inner` will be used. | `nil`
  args | Optional | table |  | `{}`
  color | Optional | color | The border color. If `nil` is passed, then the `border_color.outer` will be user for index `1` and `row_count + 1`, otherwise, `border_color.inner` will be used. | `nil`
  dashes | Optional | table | The dash pattern used for the line. By default, it is a solid line. | `{1}`
  dash_offset | Optional | number | If the line has `dashes`, then this is the initial offset. Note that line are draw left to right and top to bottom. | `0`
  caps | Optional | string | How the dashes ends are drawn. Either `"butt"` (default), `"round"` or `"square"` | `"butt"`

  ### See also:

  add_column_border | Add column border. | object methods

  ### Usage:

      local w = wibox.widget {
          -- [...] Some widgets here.
          homogeneous          = true,
          spacing              = 0,
          border_width         = 4,
          border_color         = beautiful.border_color,
          minimum_column_width = 10,
          minimum_row_height   = 10,
          layout               = wibox.layout.grid,
      }

      w:add_row_border(1, 40, { color = "red"   })
      w:add_row_border(2, 5 , { color = "green" , dashes = {5, 3, 10, 3}})
      w:add_row_border(3, 10, { color = "blue"  , dashes = {5, 3, 10, 3}, dash_offset = 5})
      w:add_row_border(4, 30, { color = "orange", dashes = {5, 40}, caps = "round"})
      w:add_row_border(5, 10, { color = "yellow"})

🔗 :add_column_border (index, height, args)
  Add column border.

  This method allows to set the width/color or a specific column rather than use the same values for all the columns.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  index |  | integer | The column index. `1` is the top border (outer) border. | Not applicable
  height | Optional | integer or nil | The border height. If `nil` is passed, then the `border_width.outer` will be user for index `1` and `column_count + 1`, otherwise, `border_width.inner` will be used. | `nil`
  args | Optional | table |  | `{}`
  color | Optional | color | The border color. If `nil` is passed, then the `border_color.outer` will be user for index `1` and `row_count + 1`, otherwise, `border_color.inner` will be used. | `nil`
  dashes | Optional | table | The dash pattern used for the line. By default, it is a solid line. | `{1}`
  dash_offset | Optional | number | If the line has `dashes`, then this is the initial offset. Note that line are draw left to right and top to bottom. | `0`
  caps | Optional | string | How the dashes ends are drawn. Either `"butt"` (default), `"round"` or `"square"` | `"butt"`

  ### See also:

  add_column_border | Add column border. | object methods

  ### Usage:

      local w = wibox.widget {
          homogeneous          = true,
          spacing              = 0,
          border_width         = 4,
          border_color         = beautiful.border_color,
          minimum_column_width = 10,
          minimum_row_height   = 10,
          layout               = wibox.layout.grid,
      }

      w:add_column_border(1, 5 , { color = "purple" })
      w:add_column_border(2, 10, { color = "cyan"   })
      w:add_column_border(3, 5 , { color = "magenta"})
      w:add_column_border(4, 5 , { color = "black"  })
      w:add_column_border(5, 10, { color = "grey"   })

🔗 :reset () · 1 signal
  Reset the grid layout. Remove all widgets and reset row and column counts
  Click to display more

  ### Emit signals:

  - reset
🔗 :set (index, widget2) -> boolean · 1 signal
  Set a widget at a specific index, replacing the current one.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index |  | number | A widget or a widget index
  widget2 |  | widget | The widget to replace the previous one with

  ### Returns:

  boolean Returns `true` if the widget was replaced successfully, `false` otherwise.
  Click to display more

  ### Emit signals:

  - `widget::replaced`
  - `self` `widget` The layout.
  - `widget` `widget` The inserted widget.
  - `previous` `widget` The previous widget.
  - `index` `number` The replaced index.
🔗 :replace_widget (widget, widget2, recursive) -> boolean · 1 signal
  Replace the first instance of `widget` in the layout with `widget2`.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  widget |  | widget | The widget to replace | Not applicable
  widget2 |  | widget | The widget to replace `widget` with | Not applicable
  recursive | Optional | boolean | Recurse into all compatible layouts to find the widget. | `false`

  ### Returns:

  boolean Returns `true` if the widget was replaced successfully, `false` otherwise.
  Click to display more

  ### Emit signals:

  - `widget::replaced`
  - `self` `widget` The layout.
  - `widget` `widget` index The inserted widget.
  - `previous` `widget` The previous widget.
  - `index` `number` The replaced index.
🔗 :swap (index1, index2) -> boolean · 1 signal
  Swap 2 widgets in a layout.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  index1 |  | number | The first widget index
  index2 |  | number | The second widget index

  ### Returns:

  boolean Returns `true` if the widget was replaced successfully, `false` otherwise.
  Click to display more

  ### Emit signals:

  - `widget::swapped`
  - `self` `widget` The layout.
  - `widget1` `widget` The first widget.
  - `widget2` `widget` The second widget.
  - `index1` `number` The first index.
  - `index1` `number` The second index.
🔗 :swap_widgets (widget1, widget2, recursive) -> boolean · 1 signal
  Swap 2 widgets in a layout.

  If `widget1` is present multiple time, only the first instance is swapped.

  Calls set internally, so the signal `widget::replaced` is emitted for both widgets as well.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  widget1 |  | widget | The first widget | Not applicable
  widget2 |  | widget | The second widget | Not applicable
  recursive | Optional | boolean | Recurse into all compatible layouts to find the widget. | `false`

  ### Returns:

  boolean Returns `true` if the widget was replaced successfully, `false` otherwise.

  ### See also:

  set | Set a widget at a specific index, replacing the current one. | object methods

  Click to display more

  ### Emit signals:

  - `widget::swapped`
  - `self` `widget` The layout.
  - `widget1` `widget` The first widget.
  - `widget2` `widget` The second widget.
  - `index1` `number` The first index.
  - `index1` `number` The second index.
🔗 :reset () · 1 signal
  Reset the layout. This removes all widgets from the layout.
  Click to display more

  ### Emit signals:

  - widget::reset
  - `self` `widget` The layout.
🔗 :add_button (button) · Inherited from wibox.widget.base
  Add a new awful.button to this widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  button |  | awful.button | The button to add.

🔗 :emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget.base
  Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.

  This is useful to track signals when there is a dynamic set of containers and layouts wrapping the widget.

  Note that this function has some flaws:

  1. The signal is only forwarded once the widget tree has been built. This happens after all currently scheduled functions have been executed. Therefore, it will not start to work right away. 2. In case the widget is present multiple times in a single widget tree, this function will also forward the signal multiple times (once per upward tree path). 3. If the widget is removed from the widget tree, the signal is still forwarded for some time, similar to the first case.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  signal_name |  | string |
  ... |  |  | Other arguments

🔗 :index (widget, recursive, ...) -> (number, widget, table) · Inherited from wibox.widget.base
  Get the index of a widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  widget |  | widget | The widget to look for.
  recursive | Optional | boolean | Recursively check accross the sub-widgets hierarchy.
  ... | Optional | widget | Additional widgets to add at the end of the sub-widgets hierarchy "path".

  ### Returns:

  1. number The widget index.
  2. widget The parent widget.
  3. table The hierarchy path between "self" and "widget".
🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  **Usage example output**:

  In slot [obj] nil nil nil In slot [obj] foo bar 42

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

  ### Usage:

      local o = gears.object{}
      -- Function can be attached to signals
      local function slot(obj, a, b, c)
          print("In slot", obj, a, b, c)
      end
      o:connect_signal("my_signal", slot)
      -- Emitting can be done without arguments. In that case, the object will be
      -- implicitly added as an argument.
      o:emit_signal "my_signal"
      -- It is also possible to add as many random arguments are required.
      o:emit_signal("my_signal", "foo", "bar", 42)
      -- Finally, to allow the object to be garbage collected (the memory freed), it
      -- is necessary to disconnect the signal or use weak_connect_signal
      o:disconnect_signal("my_signal", slot)
      -- This time, the slot wont be called as it is no longer connected.
      o:emit_signal "my_signal"

🔗 :weak_connect_signal (name, func) · Inherited from gears.object
  Connect to a signal weakly.

  This allows the callback function to be garbage collected and automatically disconnects the signal when that happens. **Warning:** Only use this function if you really, really, really know what you are doing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :disconnect_signal (name, func) · Inherited from gears.object
  Disconnect from a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback that should be disconnected.

🔗 :emit_signal (name, ...) · Inherited from gears.object
  Emit a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal
  ... |  |  | Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal()

## Signals

🔗 widget::reset
  When the layout is reset. This signal is emitted when the layout has been reset, all the widgets removed and the row and column counts reset.
🔗 widget::layout_changed · Inherited from wibox.widget.base
  When the layout (size) change. This signal is emitted when the previous results of `:layout()` and `:fit()` are no longer valid. Unless this signal is emitted, `:layout()` and `:fit()` must return the same result when called with the same arguments.

  ### See also:

  widget::redraw_needed | When the widget content changed. | signals

🔗 widget::redraw_needed · Inherited from wibox.widget.base
  When the widget content changed. This signal is emitted when the content of the widget changes. The widget will be redrawn, it is not re-layouted. Put differently, it is assumed that `:layout()` and `:fit()` would still return the same results as before.

  ### See also:

  widget::layout_changed | When the layout (size) change. | signals

🔗 button::press · Inherited from wibox.widget.base
  When a mouse button is pressed over the widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  lx |  | number | The horizontal position relative to the (0,0) position in the widget.
  ly |  | number | The vertical position relative to the (0,0) position in the widget.
  button |  | number | The button number.
  mods |  | table | The modifiers (mod4, mod1 (alt), Control, Shift)
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 button::release · Inherited from wibox.widget.base
  When a mouse button is released over the widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  lx |  | number | The horizontal position relative to the (0,0) position in the widget.
  ly |  | number | The vertical position relative to the (0,0) position in the widget.
  button |  | number | The button number.
  mods |  | table | The modifiers (mod4, mod1 (alt), Control, Shift)
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 mouse::enter · Inherited from wibox.widget.base
  When the mouse enter a widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 mouse::leave · Inherited from wibox.widget.base
  When the mouse leave a widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

## Tables

🔗 wibox.layout.grid.position
  Child widget position. Return of get_widget_position.

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  row |  |  | Top row index
  col |  |  | Left column index
  row_span |  |  | Number of rows to span
  col_span |  |  | Number of columns to span

generated by LDoc 1.5.0