-- | Conceptual documentation
module Brick.Widgets.TabularList where

import Brick.Widgets.TabularList.Types
import Brick.Widgets.Center
import Brick.Widgets.List
import Brick.Widgets.Core
import Data.Void

-- * Type Variables #TypeVariables#
--
-- $TypeVariables
-- Shared type variables
--
-- * n - the type of the resource name for the list. This is not for column headers because column headers are
-- above the list. Read [brick user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst) for more
-- details.
-- * e - the type of list elements which are also called list rows in tabular list widgets.
--
-- Mixed type variables
--
-- * w - the type that contains widths per row kind. mixed-tabular-list demo program shows how to utilize it.

-- * Rendering #Rendering#
--
-- $Rendering
-- Because tabular list widgets build on top of 'GenericList', attributes for 'GenericList' apply to tabular list
-- widgets if the attributes are defined in your brick application.
--
-- A rendering function for row headers is given a space with
--
-- @
-- 'setAvailableSize' (rowHeaderWidth, listItemHeight)
-- @
--
-- A rendering function for row columns is given a space with
--
-- @
-- 'setAvailableSize' (columnWidth, listItemHeight)
-- @
--
-- A rendering function for column headers is given a space with
--
-- @
-- 'setAvailableSize' (columnWidth, columnHeaderHeight)
-- @
--
-- A rendering function for column header row header is given a space with
--
-- @
-- 'setAvailableSize' (rowHeaderWidth, columnHeaderHeight)
-- @
--
-- If the given height and the given width for rendering functions are not claimed, the list will look broken.
--
-- The given width for rendering functions should be claimed with brick's padding functions or 'hCenter'.
--
-- The following examples show how a rendering function can claim the available width.
--
-- @
-- 'padRight' ('Pad' 1) $ 'padLeft' 'Max' content
-- @
--
-- @
-- 'padRight' 'Max' content '<+>' 'str' " "
-- @
--
-- @
-- 'padLeft' ('Pad' 1) $ 'hCenter' content
-- @
--
-- In the examples above, I used fixed padding with one space character at the left or the right to introduce gaps
-- between columns.
--
-- If there are fixed paddings used as gaps between columns, then 'WidthDeficit' should be used to remove gaps when the
-- available width is narrower than the desired column width.