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

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