Class 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

Functions

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

wibox.layout.grid.orientation Set the preferred orientation of the grid layout.
wibox.layout.grid.superpose Allow to superpose widgets in the same cell.
wibox.layout.grid.forced_num_rows Force the number of rows of the layout.
wibox.layout.grid.forced_num_cols Force the number of columns of the layout.
wibox.layout.grid.min_cols_size Set the minimum size for the columns.
wibox.layout.grid.min_rows_size Set the minimum size for the rows.
wibox.layout.grid.horizontal_spacing The spacing between columns.
wibox.layout.grid.vertical_spacing The spacing between rows.
wibox.layout.grid.spacing The spacing between rows and columns.
wibox.layout.grid.horizontal_expand Controls if the columns are expanded to use all the available width.
wibox.layout.grid.vertical_expand Controls if the rows are expanded to use all the available height.
wibox.layout.grid.expand Controls if the columns/rows are expanded to use all the available space.
wibox.layout.grid.horizontal_homogeneous Controls if the columns all have the same width or if the width of each column depends on the content.
wibox.layout.grid.vertical_homogeneous Controls if the rows all have the same height or if the height of each row depends on the content.
wibox.layout.grid.homogeneous Controls if the columns/rows all have the same size or if the size depends on the content.
wibox.layout.grid.forced_height Force a widget height.
wibox.layout.grid.forced_width Force a widget width.
wibox.layout.grid.opacity The widget opacity (transparency).
wibox.layout.grid.visible The widget visibility.

Signals

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

Tables

wibox.layout.grid.position Child widget position.

Methods

wibox.layout.grid:get_dimension () Get the number of rows and columns occupied by the widgets in the grid.
wibox.layout.grid:get_next_empty ([hint_row=1[, hint_column=1]]) Find the next available cell to insert a widget.
wibox.layout.grid:add (...) Add some widgets to the given grid layout.
wibox.layout.grid:add_widget_at (child, row, col[, row_span=1[, col_span=1]]) Add a widget to the grid layout at specific coordinate.
wibox.layout.grid:remove (...) Remove one or more widgets from the layout.
wibox.layout.grid:remove_widgets_at (row, col[, row_span=1[, col_span=1]]) Remove widgets at the coordinates.
wibox.layout.grid:get_widget_position (widget) Return the coordinates of the widget.
wibox.layout.grid:get_widgets_at (row, col[, row_span=1[, col_span=1]]) Return the widgets at the coordinates.
wibox.layout.grid:replace_widget (old, new) Replace old widget by new widget, spanning the same columns and rows.
wibox.layout.grid:insert_column (index) Insert column at index.
wibox.layout.grid:extend_column (index) Extend column at index.
wibox.layout.grid:remove_column (index) Remove column at index.
wibox.layout.grid:insert_row (index) Insert row at index.
wibox.layout.grid:extend_row (index) Extend row at index.
wibox.layout.grid:remove_row (index) Remove row at index.
wibox.layout.grid:reset () Reset the grid layout.
wibox.layout.grid:index (widget[, recursive[, ...]]) Get a widex index.
wibox.layout.grid:get_all_children () Get all direct and indirect children widgets.
wibox.layout.grid:setup (args) Set a declarative widget hierarchy description.
wibox.layout.grid:buttons (_buttons) Set/get a widget’s buttons.
wibox.layout.grid:emit_signal_recursive (signal_name, ...) Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.
wibox.layout.grid:disconnect_signal (name, func) Disconnect to a signal.
wibox.layout.grid:emit_signal (name, ...) Emit a signal.
wibox.layout.grid:connect_signal (name, func) Connect to a signal.
wibox.layout.grid:weak_connect_signal (name, func) Connect to a signal weakly.


Functions

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

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

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

  • forced_num_cols number or nil Forced number of columns (nil for automatic).
  • ... widget Widgets that should be added to the layout.

Object properties

wibox.layout.grid.orientation

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:

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

Type:

  • boolean (default false)
wibox.layout.grid.forced_num_rows
Force the number of rows of the layout.

Type:

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

Type:

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

Usage example

Type:

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

Type:

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

see spacing

Type:

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

see spacing

Type:

  • number The spacing (default 0)
wibox.layout.grid.spacing
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:

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

see expand

Type:

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

see expand

Type:

  • boolean Expand the grid into the available space (default false)
wibox.layout.grid.expand
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:

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

see homogeneous

Type:

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

see homogeneous

Type:

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

  • boolean All the columns/rows have the same size. (default true)
wibox.layout.grid.forced_height
Force a widget height.

Type:

  • height number or nil The height (nil for automatic)
wibox.layout.grid.forced_width
Force a widget width.

Type:

  • width number or nil The width (nil for automatic)
wibox.layout.grid.opacity
The widget opacity (transparency).

Type:

  • opacity number The opacity (between 0 and 1) (default 1)
wibox.layout.grid.visible
The widget visibility.

Type:

  • boolean

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
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. 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
When a mouse button is pressed over the widget.

Arguments:

  • 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
When a mouse button is released over the widget.

Arguments:

  • 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
When the mouse enter a widget.

Arguments:

  • 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
When the mouse leave a widget.

Arguments:

  • 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

wibox.layout.grid.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

Methods

wibox.layout.grid: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
wibox.layout.grid: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.
  • 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
wibox.layout.grid:add (...)
Add some widgets to the given grid layout. The widgets are assumed to span one cell
  • ... Widgets that should be added (must at least be one)
wibox.layout.grid: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)
  • 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
wibox.layout.grid:remove (...)
Remove one or more widgets from the layout.
  • ... Widgets that should be removed (must at least be one)

Returns:

    boolean If the operation is successful
wibox.layout.grid: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)
  • 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)
wibox.layout.grid:get_widget_position (widget)
Return the coordinates of the widget.
  • widget The widget

Returns:

    table The position table of the coordinates in the grid, with fields row, col, row_span and col_span.
wibox.layout.grid:get_widgets_at (row, col[, row_span=1[, col_span=1]])
Return the widgets at the coordinates.
  • 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
wibox.layout.grid:replace_widget (old, new)
Replace old widget by new widget, spanning the same columns and rows.
  • old The widget to remove
  • new The widget to add

Returns:

    boolean If the operation is successful (widget found)
wibox.layout.grid:insert_column (index)

Insert column at index.

Usage example

Usage example output:

l:insert_column(2)
  • 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
wibox.layout.grid:extend_column (index)

Extend column at index.

Usage example

Usage example output:

l:extend_column(2)
  • index number or nil Extend the column at index. If nil, the last column is extended.

Returns:

    number The index of the extended column
wibox.layout.grid:remove_column (index)

Remove column at index.

Usage example

Usage example output:

l:remove_column(2)
  • index number or nil Remove column at index. If nil, the last column is removed.

Returns:

    number The index of the removed column
wibox.layout.grid:insert_row (index)
Insert row at index.

see insert_column

  • 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
wibox.layout.grid:extend_row (index)
Extend row at index.

see extend_column

  • index number or nil Extend the row at index. If nil, the last row is extended.

Returns:

    number The index of the extended row
wibox.layout.grid:remove_row (index)
Remove row at index.

see remove_column

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

Returns:

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

Signal: widget::reset

wibox.layout.grid:index (widget[, recursive[, ...]])
Get a widex index.
  • widget The widget to look for
  • recursive Also check sub-widgets (optional)
  • ... Aditional widgets to add at the end of the "path" (optional)

Returns:

  1. The index
  2. The parent layout
  3. The path between "self" and "widget"
wibox.layout.grid:get_all_children ()
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.

Returns:

    table The children
wibox.layout.grid:setup (args)
Set a declarative widget hierarchy description. See The declarative layout system
  • args An array containing the widgets disposition
wibox.layout.grid:buttons (_buttons)
Set/get a widget’s buttons.
  • _buttons The table of buttons that should bind to the widget.
wibox.layout.grid:emit_signal_recursive (signal_name, ...)
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.
  • signal_name string
  • ... Other arguments
wibox.layout.grid:disconnect_signal (name, func)
Disconnect to a signal.
  • name string The name of the signal
  • func function The callback that should be disconnected
wibox.layout.grid:emit_signal (name, ...)
Emit a signal.
  • 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()
wibox.layout.grid:connect_signal (name, func)
Connect to a signal.
  • name string The name of the signal
  • func function The callback to call when the signal is emitted
wibox.layout.grid:weak_connect_signal (name, func)
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.

  • name string The name of the signal
  • func function The callback to call when the signal is emitted
generated by LDoc 1.4.6 Last updated 2017-06-21 07:21:06