Module: wibox.layout.grid

A grid layout.

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.

Usage example

local l = wibox.widget {
    homogeneous   = true,
    spacing       = 5,
    min_cols_size = 10,
    min_rows_size = 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)

Using the declarative system, widgets are automatically added next to each other spanning only one cell.

Usage example

Usage:

    wibox.widget {
        generic_widget( 'first'  ),
        generic_widget( 'second' ),
        generic_widget( 'third'  ),
        generic_widget( 'fourth' ),
        forced_num_cols = 2,
        forced_num_rows = 2,
        homogeneous     = true,
        expand          = true,
        layout = wibox.layout.grid
    }
    

Info:

  • Copyright: 2017 getzze
  • Author: getzze

Constructors

wibox.layout.grid ([orientation="y"]) 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.
forced_num_rows number or nil Force the number of rows of the layout.
forced_num_cols number or nil Force the number of columns of the layout.
min_cols_size number Set the minimum size for the columns.
min_rows_size number Set the minimum size for the rows.
horizontal_spacing number The spacing between columns.
vertical_spacing number The spacing between rows.
spacing number The spacing between rows and columns.
horizontal_expand boolean Controls if the columns are expanded to use all the available width.
vertical_expand boolean Controls if the rows are expanded to use all the available height.
expand boolean Controls if the columns/rows are expanded to use all the available space.
horizontal_homogeneous boolean Controls if the columns all have the same width or if the width of each column depends on the content.
vertical_homogeneous boolean Controls if the rows all have the same height or if the height of each row depends on the content.
homogeneous boolean Controls if the columns/rows all have the same size or if the size depends on the content.
children table Get or set the children elements. Inherited from wibox.widget
all_children table Get all direct and indirect children widgets. Inherited from wibox.widget
forced_height number or nil Force a widget height. Inherited from wibox.widget
forced_width number or nil Force a widget width. Inherited from wibox.widget
opacity number The widget opacity (transparency). Inherited from wibox.widget
visible boolean The widget visibility. Inherited from wibox.widget
buttons table The widget buttons. Inherited from wibox.widget

Object methods

:get_dimension () Get the number of rows and columns occupied by the widgets in the grid.
:get_next_empty ([hint_row=1[, hint_column=1]]) Find the next available cell to insert a widget.
:add (...) Add some widgets to the given grid layout.
:add_widget_at (child, row, col[, row_span=1[, col_span=1]]) Add a widget to the grid layout at specific coordinate.
:remove (...) Remove one or more widgets from the layout.
:remove_widgets_at (row, col[, row_span=1[, col_span=1]]) Remove widgets at the coordinates.
:get_widget_position (widget) Return the coordinates of the widget.
:get_widgets_at (row, col[, row_span=1[, col_span=1]]) Return the widgets at the coordinates.
:replace_widget (old, new) Replace old widget by new widget, spanning the same columns and rows.
:insert_column (index) Insert column at index.
:extend_column (index) Extend column at index.
:remove_column (index) Remove column at index.
:insert_row (index) Insert row at index.
:extend_row (index) Extend row at index.
:remove_row (index) Remove row at index.
:reset () Reset the grid layout.
:set (index, widget2) Set a widget at a specific index, replace the current one.
:replace_widget (widget, widget2[, recursive=false]) Replace the first instance of widget in the layout with widget2.
:swap (index1, index2) Swap 2 widgets in a layout.
:swap_widgets (widget1, widget2[, recursive=false]) Swap 2 widgets in a layout.
:reset () Reset a ratio layout.
:setup {[args]} Set a declarative widget hierarchy description. Inherited from wibox.widget
:add_button (button) Add a new awful.button to this widget. Inherited from wibox.widget
:emit_signal_recursive (signal_name, ...) Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. Inherited from wibox.widget
:emit_signal (name, ...) Emit a signal. Inherited from gears.object
: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

Signals

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

Tables

position Child widget position.


Constructors

wibox.layout.grid ([orientation="y"])
Return a new grid layout.

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

Parameters:

  • orientation string The preferred grid extension direction. (default "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:

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

  • 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.

Allowed values are “horizontal” and “vertical”. When calling get_next_empty, empty cells are browsed differently:

  • for “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.

  • for “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.

Usage example

Usage example output:

l = wibox.layout {
    forced_num_cols = 2,
    forced_num_rows = 2,
    homogeneous     = true,
    layout = wibox.layout.grid
}
l:set_orientation('vertical') -- change to 'horizontal'
l:add(...)

Type constraints:

  • string Preferred orientation: “horizontal” or “vertical”. (default "vertical")
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.

Usage example

forced_num_rows (number or nil)
Force the number of rows of the layout.

Type constraints:

  • number number or nil Forced number of rows (nil for automatic). (default nil)
forced_num_cols (number or nil)
Force the number of columns of the layout.

Type constraints:

  • number number or nil Forced number of columns (nil for automatic). (default nil)
min_cols_size (number)
Set the minimum size for the columns.

Usage example

Type constraints:

  • number Minimum size of the columns. (default 0)
min_rows_size (number)
Set the minimum size for the rows.

Type constraints:

  • number Minimum size of the rows. (default 0)
horizontal_spacing (number)
The spacing between columns.

see spacing

Type constraints:

  • number The spacing (default 0)
vertical_spacing (number)
The spacing between rows.

see spacing

Type constraints:

  • number The spacing (default 0)
spacing (number)
The spacing between rows and columns. Set both horizontal_spacing and vertical_spacing to the same value. Get the value horizontal_spacing or vertical_spacing defined by the preferred orientation.

Usage example

Type constraints:

  • number The spacing (default 0)
horizontal_expand (boolean)
Controls if the columns are expanded to use all the available width.

see expand

Type constraints:

  • boolean Expand the grid into the available space (default false)
vertical_expand (boolean)
Controls if the rows are expanded to use all the available height.

see expand

Type constraints:

  • boolean Expand the grid into the available space (default false)
expand (boolean)
Controls if the columns/rows are expanded to use all the available space. Set both horizontal_expand and vertical_expand to the same value. Get the value horizontal_expand or vertical_expand defined by the preferred orientation.

Usage example

Type constraints:

  • boolean Expand the grid into the available space (default false)
horizontal_homogeneous (boolean)
Controls if the columns all have the same width or if the width of each column depends on the content.

see homogeneous

Type constraints:

  • boolean All the columns have the same width. (default true)
vertical_homogeneous (boolean)
Controls if the rows all have the same height or if the height of each row depends on the content.

see homogeneous

Type constraints:

  • boolean All the rows have the same height. (default true)
homogeneous (boolean)
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.

Usage example

Type constraints:

  • boolean All the columns/rows have the same size. (default true)
children (table) · Inherited from wibox.widget
Get or set the children elements.

Type constraints:

  • children table The children.
all_children (table) · Inherited from wibox.widget
Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow id the widget, or any of its children, contain (directly or indirectly) itself.

Type constraints:

  • children table The children.
forced_height (number or nil) · Inherited from wibox.widget
Force a widget height.

Type constraints:

  • height number or nil The height (nil for automatic)
forced_width (number or nil) · Inherited from wibox.widget
Force a widget width.

Type constraints:

  • width number or nil The width (nil for automatic)
opacity (number) · Inherited from wibox.widget
The widget opacity (transparency).

Type constraints:

  • opacity number The opacity (between 0 and 1) (default 1)
visible (boolean) · Inherited from wibox.widget
The widget visibility.
buttons (table) · Inherited from wibox.widget
The widget buttons.

The table contains a list of awful.button objects.

See also:

Object methods

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

Returns:

    number,number The number of rows and columns
:get_next_empty ([hint_row=1[, hint_column=1]])
Find the next available cell to insert a widget. The grid is browsed according to the orientation.

Parameters:

  • hint_row number The row coordinate of the last occupied cell. (default 1)
  • hint_column number The column coordinate of the last occupied cell. (default 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.

Parameters:

  • ... Widgets that should be added (must at least be one)
:add_widget_at (child, row, col[, row_span=1[, col_span=1]])

Add a widget to the grid layout at specific coordinate.

Usage example

Usage example output:

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

Parameters:

  • child Widget that should be added
  • row number Row number for the top left corner of the widget
  • col number Column number for the top left corner of the widget
  • row_span number The number of rows the widget spans. (default 1)
  • col_span number The number of columns the widget spans. (default 1)

Returns:

    boolean index If the operation is successful
:remove (...)
Remove one or more widgets from the layout.

Parameters:

  • ... Widgets that should be removed (must at least be one)

Returns:

    boolean If the operation is successful
:remove_widgets_at (row, col[, row_span=1[, col_span=1]])

Remove widgets at the coordinates.

Usage example

Usage example output:

l:remove_widgets_at(1,1)

Parameters:

  • row number The row coordinate of the widget to remove
  • col number The column coordinate of the widget to remove
  • row_span number The number of rows the area to remove spans. (default 1)
  • col_span number The number of columns the area to remove spans. (default 1)

Returns:

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

Parameters:

  • 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=1[, col_span=1]])
Return the widgets at the coordinates.

Parameters:

  • row number The row coordinate of the widget
  • col number The column coordinate of the widget
  • row_span number The number of rows to span. (default 1)
  • col_span number The number of columns to span. (default 1)

Returns:

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

Parameters:

  • old The widget to remove
  • new The widget to add

Returns:

    boolean If the operation is successful (widget found)
:insert_column (index)

Insert column at index.

Usage example

Usage example output:

l:insert_column(2)

Parameters:

  • 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)

Extend column at index.

Usage example

Usage example output:

l:extend_column(2)

Parameters:

  • 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)

Remove column at index.

Usage example

Usage example output:

l:remove_column(2)

Parameters:

  • 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)
Insert row at index.

see insert_column

Parameters:

  • 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)
Extend row at index.

see extend_column

Parameters:

  • 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)
Remove row at index.

see remove_column

Parameters:

  • index number or nil Remove row at index. If nil, the last row is removed.

Returns:

    number The index of the removed row
:reset ()
Reset the grid layout. Remove all widgets and reset row and column counts

Signal: widget::reset

:set (index, widget2) · 1 signal
Set a widget at a specific index, replace the current one.

Parameters:

  • index number A widget or a widget index
  • widget2 widget The widget to take the place of the first one

Returns:

    boolean If the operation is successful

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.
:replace_widget (widget, widget2[, recursive=false]) · 1 signal
Replace the first instance of widget in the layout with widget2.

Signal: widget::replaced The argument is the new widget and the old one and the index.

Parameters:

  • widget widget The widget to replace
  • widget2 widget The widget to replace widget with
  • recursive boolean Dig in all compatible layouts to find the widget. (default false)

Returns:

    boolean If the operation is successful

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) · 1 signal
Swap 2 widgets in a layout.

Parameters:

  • index1 number The first widget index
  • index2 number The second widget index

Returns:

    boolean If the operation is successful

Click to display more

Emit signals:

  • widget::swapped
    • self widget The layout.
    • widget1 widget index The first widget.
    • widget2 widget index The second widget.
    • index1 number The first index.
    • index1 number The second index.
:swap_widgets (widget1, widget2[, recursive=false]) · 1 signal
Swap 2 widgets in a layout. If widget1 is present multiple time, only the first instance is swapped Signal: widget::swapped The arguments are both widgets and both (new) indexes. if the layouts not the same, then only widget::replaced will be emitted.

Parameters:

  • widget1 widget The first widget
  • widget2 widget The second widget
  • recursive boolean Dig in all compatible layouts to find the widget. (default false)

Returns:

    boolean If the operation is successful

Click to display more

Emit signals:

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

Emit signals:

:setup {[args]} · Inherited from wibox.widget
Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

  • args An array containing the widgets disposition
:add_button (button) · Inherited from wibox.widget
Add a new awful.button to this widget.

Parameters:

  • button awful.button The button to add.
:emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget
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.

Parameters:

  • signal_name string
  • ... Other arguments
:emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

  • 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().
:connect_signal (name, func) · Inherited from gears.object
Connect to a signal.

Parameters:

  • name string The name of the signal.
  • func function The callback to call when the signal is emitted.
: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 string The name of the signal.
  • func function The callback to call when the signal is emitted.

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
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 · Inherited from wibox.widget
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:

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

Arguments:

  • 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 The entry from the result of wibox.drawable: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:

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

Arguments:

  • 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 The entry from the result of wibox.drawable: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::enter · Inherited from wibox.widget
When the mouse enter a widget.

Arguments:

  • self table The current object instance itself.
  • find_widgets_result The entry from the result of wibox.drawable: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::leave · Inherited from wibox.widget
When the mouse leave a widget.

Arguments:

  • self table The current object instance itself.
  • find_widgets_result The entry from the result of wibox.drawable: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:

Tables

position
Child widget position. Return of get_widget_position.

Fields:

  • 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.4.6 Last updated 2030-01-01 00:00:00