Table

Table Widget API

Example usage for creating a simple table:

Iris.Table({ 4, true })
do
    Iris.SetHeaderColumnIndex(1)

    -- for each row
    for i = 0, 10 do

        -- for each column
        for j = 1, 4 do
            if i == 0 then
                -- 
                Iris.Text({ `H: {j}` })
            else
                Iris.Text({ `R: {i}, C: {j}` })
            end

            -- move the next column (and row when necessary)
            Iris.NextColumn()
        end
    end

Properties

Table

WidgetHasChildren

</>

Table.Table: Iris.Table

A layout widget which allows children to be displayed in configurable columns and rows. Highly configurable for many different options, with options for custom width columns as configured by the user, or automatically use the best size.

When Resizable is enabled, the vertical columns can be dragged horizontally to increase or decrease space. This is linked to the widths state, which controls the width of each column. This is also dependent on whether the FixedWidth argument is enabled. By default, the columns will scale with the width of the table overall, therefore taking up a percentage, and the widths will be in the range of 0 to 1 as a float. If FixedWidth is enabled, then the widths will be in pixels and have a value of > 2 as an integer.

ProportionalWidth determines whether each column has the same width, or individual. By default, each column will take up an equal proportion of the total table width. If true, then the columns will be allocated a width proportional to their total content size, meaning wider columns take up a greater share of the total available space. For a fixed width table, by default each column will take the max width of all the columns. When true, each column width will the minimum to fit the children within.

LimitTableWidth is used when FixedWidth is true. It will cut off the table horizontally after the last column.

INFO

Once the NumColumns is set, it is not possible to change it without some extra code. The best way to do this is by using Iris.PushConfig() and Iris.PopConfig() which will automatically redraw the widget when the columns change.

local numColumns = 4
Iris.PushConfig({ columns = numColumns })
Iris.Table({ numColumns, ...})
do
    ...
end
Iris.End()
Iris.PopConfig()

:::danger Error: nil Always ensure that the number of elements in the widths state is greater or equal to the new number of columns when changing the number of columns.

:::

hasChildren = true
hasState = false
Arguments = {
    NumColumns: number, -- number of columns in the table, cannot be changed
    Header: boolean? = false, -- display a header row for each column
    RowBackground: boolean? = false, -- alternating row background colours
    OuterBorders: boolean? = false, -- outer border on the entire table
    InnerBorders: boolean? = false, -- inner bordres on the entire table
    Resizable: boolean? = false, -- the columns can be resized by dragging or state
    FixedWidth: boolean? = false, -- columns takes up a fixed pixel width, rather than a proportion of the total available
    ProportionalWidth: boolean? = false, -- minimises the width of each column individually
    LimitTableWidth: boolean? = false, -- when a fixed width, cut of any unused space
}
Events = {
    hovered: () -> boolean
}
States = {
    widths: State<{ number }>? -- the widths of each column if Resizable
}

Functions

NextColumn

</>

Table.NextColumn() → ()

In a table, moves to the next available cell. If the current cell is in the last column, then moves to the cell in the first column of the next row.

NextRow

</>

Table.NextRow() → ()

In a table, moves to the cell in the first column of the next row.

SetColumnIndex

</>

Table.SetColumnIndex(index: number) → ()

In a table, moves to the cell in the given column in the same previous row.

Will erorr if the given index is not in the range of 1 to NumColumns.

SetRowIndex

</>

Table.SetRowIndex(index: number) → ()

In a table, moves to the cell in the given row with the same previous column.

NextHeaderColumn

</>

Table.NextHeaderColumn() → ()

In a table, moves to the cell in the next column in the header row (row index 0). Will loop around from the last column to the first.

SetHeaderColumnIndex

</>

Table.SetHeaderColumnIndex(index: number) → ()

In a table, moves to the cell in the given column in the header row (row index 0).

Will erorr if the given index is not in the range of 1 to NumColumns.

SetColumnWidth

</>

Table.SetColumnWidth(

index: number,

width: number

) → ()

In a table, sets the width of the given column to the given value by changing the Table's widths state. When the FixedWidth argument is true, the width should be in pixels >2, otherwise as a float between 0 and 1.

Will erorr if the given index is not in the range of 1 to NumColumns.