brick-2.9: A declarative terminal user interface library

Safe Haskell | None
Language | Haskell2010

Brick.Widgets.Table

Contents

- Types
- Construction
- Configuration
- Rendering
- Low-level API

Description

This module provides a table widget that can draw other widgets in a table layout, draw borders between rows and columns, and allow configuration of row and column alignment. To get started, see `table`.

Synopsis

- data Table n
- data ColumnAlignment
  - = AlignLeft
  - | AlignCenter
  - | AlignRight
- data RowAlignment
  - = AlignTop
  - | AlignMiddle
  - | AlignBottom
- data TableException
  - = TEUnequalRowSizes
  - | TEInvalidCellSizePolicy
- table :: [[Widget n]] -> Table n
- alignLeft :: Int -> Table n -> Table n
- alignRight :: Int -> Table n -> Table n
- alignCenter :: Int -> Table n -> Table n
- alignTop :: Int -> Table n -> Table n
- alignMiddle :: Int -> Table n -> Table n
- alignBottom :: Int -> Table n -> Table n
- setColAlignment :: ColumnAlignment -> Int -> Table n -> Table n
- setRowAlignment :: RowAlignment -> Int -> Table n -> Table n
- setDefaultColAlignment :: ColumnAlignment -> Table n -> Table n
- setDefaultRowAlignment :: RowAlignment -> Table n -> Table n
- surroundingBorder :: Bool -> Table n -> Table n
- rowBorders :: Bool -> Table n -> Table n
- columnBorders :: Bool -> Table n -> Table n
- renderTable :: Table n -> Widget n
- data RenderedTableCells n = RenderedTableCells {
  - renderedTableRows :: [[Widget n]]
  - renderedTableColumnWidths :: [Int]
  - renderedTableRowHeights :: [Int]
  - borderConfiguration :: BorderConfiguration
  }
- data BorderConfiguration = BorderConfiguration {
  - drawSurroundingBorder :: Bool
  - drawRowBorders :: Bool
  - drawColumnBorders :: Bool
  }
- tableCellLayout :: Table n -> RenderM n (RenderedTableCells n)
- addBorders :: RenderedTableCells n -> RenderM n (Widget n)
- alignColumns :: [ColumnAlignment] -> [Int] -> [Widget n] -> [Widget n]

# Types

data Table n Source #

A table data structure for widgets of type `Widget` `n`. Create a table with `table`.

data ColumnAlignment Source #

Column alignment modes. Use these modes with the alignment functions in this module to configure column alignment behavior.

Constructors

AlignLeft | Align all cells to the left.
AlignCenter | Center the content horizontally in all cells in the column.
AlignRight | Align all cells to the right.

#### Instances

Instances details

Read ColumnAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods readsPrec :: Int -> ReadS ColumnAlignment Source # readList :: ReadS [ColumnAlignment] Source # readPrec :: ReadPrec ColumnAlignment Source # readListPrec :: ReadPrec [ColumnAlignment] Source #
Show ColumnAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods showsPrec :: Int -> ColumnAlignment -> ShowS Source # show :: ColumnAlignment -> String Source # showList :: [ColumnAlignment] -> ShowS Source #
Eq ColumnAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods (==) :: ColumnAlignment -> ColumnAlignment -> Bool Source # (/=) :: ColumnAlignment -> ColumnAlignment -> Bool Source #

data RowAlignment Source #

Row alignment modes. Use these modes with the alignment functions in this module to configure row alignment behavior.

Constructors

AlignTop | Align all cells to the top.
AlignMiddle | Center the content vertically in all cells in the row.
AlignBottom | Align all cells to the bottom.

#### Instances

Instances details

Read RowAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods readsPrec :: Int -> ReadS RowAlignment Source # readList :: ReadS [RowAlignment] Source # readPrec :: ReadPrec RowAlignment Source # readListPrec :: ReadPrec [RowAlignment] Source #
Show RowAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods showsPrec :: Int -> RowAlignment -> ShowS Source # show :: RowAlignment -> String Source # showList :: [RowAlignment] -> ShowS Source #
Eq RowAlignment Source # |
Instance details Defined in Brick.Widgets.Table Methods (==) :: RowAlignment -> RowAlignment -> Bool Source # (/=) :: RowAlignment -> RowAlignment -> Bool Source #

data TableException Source #

A table creation exception.

Constructors

TEUnequalRowSizes | Rows did not all have the same number of cells.
TEInvalidCellSizePolicy | Some cells in the table did not use the `Fixed` size policy for both horizontal and vertical sizing.

#### Instances

Instances details

Exception TableException Source # |
Instance details Defined in Brick.Widgets.Table Methods toException :: TableException -> SomeException Source # fromException :: SomeException -> Maybe TableException Source # displayException :: TableException -> String Source # backtraceDesired :: TableException -> Bool Source #
Read TableException Source # |
Instance details Defined in Brick.Widgets.Table Methods readsPrec :: Int -> ReadS TableException Source # readList :: ReadS [TableException] Source # readPrec :: ReadPrec TableException Source # readListPrec :: ReadPrec [TableException] Source #
Show TableException Source # |
Instance details Defined in Brick.Widgets.Table Methods showsPrec :: Int -> TableException -> ShowS Source # show :: TableException -> String Source # showList :: [TableException] -> ShowS Source #
Eq TableException Source # |
Instance details Defined in Brick.Widgets.Table Methods (==) :: TableException -> TableException -> Bool Source # (/=) :: TableException -> TableException -> Bool Source #

# Construction

table :: [[Widget n]] -> Table n Source #

Construct a new table.

The argument is the list of rows with the topmost row first, with each element of the argument list being the contents of the cells in in each column of the respective row, with the leftmost cell first.

Each row's height is determined by the height of the tallest cell in that row, and each column's width is determined by the width of the widest cell in that column. This means that control over row and column dimensions is a matter of controlling the size of the individual cells, such as by wrapping cell contents in padding, `fill` and `hLimit` or `vLimit`, etc. This also means that it is not necessary to explicitly set the width of most table cells because the table will determine the per-row and per-column dimensions by looking at the largest cell contents. In particular, this means that the table's alignment logic only has an effect when a given cell's contents are smaller than the maximum for its row and column, thus giving the table some way to pad the contents to result in the desired alignment.

By default:

- All columns are left-aligned. Use the alignment functions in this module to change that behavior.
- All rows are top-aligned. Use the alignment functions in this module to change that behavior.
- The table will draw borders between columns, between rows, and around the outside of the table. Border-drawing behavior can be configured with the API in this module. Note that tables always draw with `joinBorders` enabled. If a cell's contents has smart borders but you don't want those borders to connect to the surrounding table borders, wrap the cell's contents with `freezeBorders`.

All cells of all rows MUST use the `Fixed` growth policy for both horizontal and vertical growth. If the argument list contains any cells that use the `Greedy` policy, this function will raise a `TableException`.

All rows MUST have the same number of cells. If not, this function will raise a `TableException`.

# Configuration

alignLeft :: Int -> Table n -> Table n Source #

Align the specified column to the left. The argument is the column index, starting with zero. Silently does nothing if the index is out of range.

alignRight :: Int -> Table n -> Table n Source #

Align the specified column to the right. The argument is the column index, starting with zero. Silently does nothing if the index is out of range.

alignCenter :: Int -> Table n -> Table n Source #

Align the specified column to center. The argument is the column index, starting with zero. Silently does nothing if the index is out of range.

alignTop :: Int -> Table n -> Table n Source #

Align the specified row to the top. The argument is the row index, starting with zero. Silently does nothing if the index is out of range.

alignMiddle :: Int -> Table n -> Table n Source #

Align the specified row to the middle. The argument is the row index, starting with zero. Silently does nothing if the index is out of range.

alignBottom :: Int -> Table n -> Table n Source #

Align the specified row to bottom. The argument is the row index, starting with zero. Silently does nothing if the index is out of range.

setColAlignment :: ColumnAlignment -> Int -> Table n -> Table n Source #

Set the alignment for the specified column index (starting at zero). Silently does nothing if the index is out of range.

setRowAlignment :: RowAlignment -> Int -> Table n -> Table n Source #

Set the alignment for the specified row index (starting at zero). Silently does nothing if the index is out of range.

setDefaultColAlignment :: ColumnAlignment -> Table n -> Table n Source #

Set the default column alignment for columns with no explicitly configured alignment.

setDefaultRowAlignment :: RowAlignment -> Table n -> Table n Source #

Set the default row alignment for rows with no explicitly configured alignment.

surroundingBorder :: Bool -> Table n -> Table n Source #

Configure whether the table draws a border on its exterior.

rowBorders :: Bool -> Table n -> Table n Source #

Configure whether the table draws borders between its rows.

columnBorders :: Bool -> Table n -> Table n Source #

Configure whether the table draws borders between its columns.

# Rendering

renderTable :: Table n -> Widget n Source #

Render the table.

# Low-level API

data RenderedTableCells n Source #

The result of performing table cell intermediate rendering and layout.

Constructors

RenderedTableCells |

Fields

- renderedTableRows :: [[Widget n]]

  The table's cells in row-major order.

- renderedTableColumnWidths :: [Int]

  The widths of the table's columns.

- renderedTableRowHeights :: [Int]

  The heights of the table's rows.

- borderConfiguration :: BorderConfiguration

  The border configuration to use.

data BorderConfiguration Source #

A border configuration for a table.

Constructors

BorderConfiguration |

Fields

- drawSurroundingBorder :: Bool
- drawRowBorders :: Bool
- drawColumnBorders :: Bool

tableCellLayout :: Table n -> RenderM n (RenderedTableCells n) Source #

addBorders :: RenderedTableCells n -> RenderM n (Widget n) Source #

Augment rendered table cells with borders according to the border configuration accompanying the cells.

alignColumns Source #

Arguments

:: [ColumnAlignment] | The column alignments to use for each widget, respectively.
-> [Int] | The width of each column in terminal columns, respectively.
-> [Widget n] | The column cells to align.
-> [Widget n] |

Given a "table row" of widgets, align each one according to the list of specified column alignments in columns of the specified widths.