Rainbox

Create grids of (possibly) colorful boxes.

For an introduction, see Rainbox.Tutorial. That file is written in literate Haskell, so you will want to look at the source itself. HsColour does not do very well with literate Haskell, so you will want to view the file in your text editor or on Github:

https://github.com/massysett/rainbox/blob/master/lib/Rainbox/Tutorial.lhs

This module only helps you create simple grids of cells, rather like a spreadsheet that does not allow you to merge or split cells. If your needs are more complicated, use Rainbox.Box, which allows you to build Boxes of arbitrary complexity by pasting simpler Boxes together. (You can of course use this module together with Rainbox.Box to create very complex layouts.)

Backgrounds

data Background

Background colors to use when inserting necessary padding.

Constructors

Background

Fields

boxBackground8 :: Color8

boxBackground256 :: Color256

Instances

Eq Background

Show Background

defaultBackground :: Background

Use the default background colors of the current terminal.

backgroundFromChunk :: Chunk -> Background

same :: Color8 -> Background

Use the same color for 8 and 256-color backgrounds.

Alignment

data Align a

Alignment.

Instances

Eq a => Eq (Align a)

Show a => Show (Align a)

data Horiz

Horizontal alignment.

Instances

Eq Horiz

Show Horiz

data Vert

Vertical alignment.

Instances

Eq Vert

Show Vert

top :: Align Vert

bottom :: Align Vert

left :: Align Horiz

right :: Align Horiz

center :: Align a

Bar

newtype Bar

Occupies a single row on screen. The Chunk you place in a Bar should not have any control characters such as newlines or tabs, as rainbox assumes that each character in a Bar takes up one screen column and that each character does not create newlines. Leave newline handling up to rainbox. However, rainbox will not check to make sure that your inputs do not contain newlines, tabs, or other spurious characters. Similarly, use of combining characters will create unexpected results, as Rainbox will see something that takes up (for instance) two characters and think it takes up two screen columns, when in reality it will take up only one screen column. So, if you need accented characters, use a single Unicode code point, not two code points. For example, for é, use U+00E9, not U+0065 and U+0301.

Constructors

Bar

Fields

unBar :: [Chunk]

Instances

Eq Bar

Show Bar

IsString Bar

Monoid Bar

HasWidth Bar

Cell

data Cell

A Cell consists of multiple screen lines; each screen line is a Bar.

Constructors

Cell

Fields

bars :: [Bar]

Each Bar is one line on the screen.

horiz :: Align Horiz

How this Cell aligns compared to the other Cell in its column; use left, center, or right.

vert :: Align Vert

How this Cell aligns compared to other Cell in its row; use top, center, or bottom.

background :: Background

Background color for necessary padding that is added to the Cell to make it the correct width and height. Does not affect the Chunk contained in the bars; these will use the colors that are designated in the Chunk itself.

Instances

Eq Cell

Show Cell

IsString Cell

Creates a Cell with a left horizontal alignment, a top vertical alignment, and a defaultBackground. The cell will be one Bar tall and contain the text given in the string.

Creating Box and gluing them together

For simple needs you will only need gridByRows or gridByCols; boxCells and glueBoxes are provided for more complex needs.

gridByRows :: [[Cell]] -> Box

Creates a single Box from a list of rows of Cell. Each list is a row of Cell. The list of rows is from top to bottom; within each row, the cells are given from left to right.

This function is partial. Each list of Cell must be the same length; otherwise, your program will crash. Since you will typically generate the list of rows using map or list comprehensions or the like, this isn't typically a problem; if it is a problem, then check the inputs to this function with checkGrid before you apply it.

gridByCols :: [[Cell]] -> Box

Creates a single Box from a list of columns of Cell. Each list is a column of Cell. The list of columns is from left to right; within each column, the cells are given from top to bottom.

This function is partial. Each list of Cell must be the same length; otherwise, your program will crash. Since you will typically generate the list of columns using map or list comprehensions or the like, this isn't typically a problem; if it is a problem, then check the inputs to this function with checkGrid before you apply it.

checkGrid :: [[Cell]] -> Bool

Checks the input to gridByRows or gridByCols to ensure that it is safe. True if the list of list of Cell is safe for either of these functions; False if not.

boxCells :: (Ix col, Ix row) => Array (col, row) Cell -> Array (col, row) Box

Transforms a grid of Cell to a grid of Box by adding necessary padding to each Cell. In every row of the array, all the Box will have equal height; in every column of the array, all the Box will have equal width.

glueBoxes :: (Ix col, Ix row) => Array (col, row) Box -> Box

Use catH and catV to fuse an array of Box into a single Box. For example, if the bounds of the array are ((0,0),(3,5)), then the array has the number of cells given by rangeSize ((0,0), (3,5)) (that is, 24). The upper left corner is (0,0) and the lower right corner is (3,5); the upper right and lower left corners are (3,0) and (0,5), respectively.

Rendering

render :: Box -> [Chunk]

Convert a Box to Rainbow Chunks. You can then print it using putChunks or the like.

printBox :: Box -> IO ()

Prints a Box to standard output. If standard output is not a terminal, no colors are used. Otherwise, colors are used if your TERM environment variable suggests they are available.