UI

Layout elements for your TUI view

Your view takes a model and returns an Element. The simplest element is text:

view model =
    UI.text [] "Hello!"

But you can construct more complex layouts by composing an element out of other elements.

Your primary building blocks are row and column. These can be nested to construct simple or complex layouts. For example:

UI.row []
    [ UI.text [] "Left "
    , UI.column []
        [ UI.text [] "Right 1"
        , UI.text [] "Right 2"
        ]
    ]

Which would render like this:

Left Right 1
     Right 2

There's also a special bordered element to wrap other elements in a border.

Your innermost element will be text.

All elements can be styled by passing array of attributes as the first argument.

type Element

Basic building block of of the view.
row : Array Attribute -> Array Element -> Element

Lay out elements horizontally.

For example:

row [] 
    [ text [] "one "
    , text [] "two "
    , text [] "three " 
    ]

Would output:

one two three

This is helpful when you want a columnar layout. For example:

row []
    [ text [] " one\n two\n three"
    , text [] " four\n five\n six"
    ]

Would output:

one   four
two   five
three six

Instead of newlines, you could use the column function:

row []
    [ column [] 
        [ text [] "one"
        , text [] "two"
        , text [] "three"
        ]
    , column [] 
        [ text [] "four"
        , text [] "five"
        , text [] "six"
        ]
    ]

Which would also output:

one   four
two   five
three six

This becomes very powerful as you continue to nest rows and columns!

The first argument is an array of UI.Attribute values. Use this to apply styles to all elements in the row, even nested elements.
column : Array Attribute -> Array Element -> Element

Lay out elements vertically.

For example:

column [] 
    [ text [] "one "
    , text [] "two "
    , text [] "three " 
    ]

Would output:

one
two
three

This becomes very powerful when nested in a row function:

row []
    [ column [] 
        [ text [] "one"
        , text [] "two"
        , text [] "three"
        ]
    , column [] 
        [ text [] "four"
        , text [] "five"
        , text [] "six"
        ]
    ]

Which would output output:

one   four
two   five
three six

The first argument is an array of UI.Attribute values. Use this to apply styles to all elements in the column, even nested elements.
bordered : Array Attribute -> Border -> Element -> Element

Wrap an element in a border.

The different types of borders are in UI.Border.

The element you pass to this function can be as large or deeply nested as you want, and the border will be around the whole thing.

Borders can also be nested and styled like any other element.
text : Array Attribute -> String -> Element

A text element.

The first argument is an array of UI.Attribute values used to style the text.

Note that text will not wrap automatically, though explicit newlines will be preserved.
toString : Int -> Element -> String

Return the element as a string that can be printed to the terminal.

You shouldn't need this in normal apps.

gren-tui uses this internally to convert your view to something that can printed to the terminal.

But it may be useful if you're writing a package or doing something weird. Have fun!

The first parameter is the maximum width in visible characters. You will usually want to use Terminal.Configuration.columns for this.

For example:

toString 80 <|
    column []
        [ text [] "12"
        , text [] "1234"
        ]

will return:

"12  \n1234"

Any content longer than the maximum visible width will be removed.

For example:

toString 3 <|
    column []
        [ text [] "12"
        , text [] "1234"
        ]

will return:

"12 \n123"