Tui.Screen.Advanced

Framework-level helpers for inspecting and rebuilding styled terminal lines.

Most app code should stay in Tui.Screen. Reach for this module when you need to preserve styling while transforming rendered text. Typical use cases are highlighting search matches in an already-styled buffer, applying syntax coloring to rendered output, splitting lines at arbitrary character positions without losing styles, or implementing diff-style overlays. The tui-widgets package uses this internally for its search and layout features.

import Tui.Screen as Screen
import Tui.Screen.Advanced as Advanced


screen : Screen.Screen
screen =
    Screen.concat
        [ Screen.text "hello "
        , Screen.text "world" |> Screen.fg Ansi.Color.green
        ]


screen
    |> Advanced.toLines
    |> List.head
    |> Maybe.withDefault []
    |> Advanced.fromLine
    |> Screen.toString

Lines

type alias Line =

List Span

A rendered screen line represented as styled spans.

import Tui.Screen.Advanced as Advanced


line : Advanced.Line
line =
    []

type alias Span =

{ text : String

, style : Style

}

A styled segment within a rendered line. Obtain spans by calling toLines on a rendered Tui.Screen.Screen. Inspect the style field with styleForeground, styleBackground, styleAttributes, and styleHyperlink.

toLines : Screen -> List Line

Flatten a Tui.Screen.Screen into rendered lines of styled spans.

import Ansi.Color
import Tui.Screen as Screen
import Tui.Screen.Advanced as Advanced


lines : List Advanced.Line
lines =
    Screen.concat
        [ Screen.text "hello "
        , Screen.text "world" |> Screen.fg Ansi.Color.green
        ]
        |> Advanced.toLines

Rebuilding

fromLine : Line -> Screen

Rebuild a single rendered line from styled spans.

An empty line becomes Tui.Screen.blank, preserving the fact that it takes up one terminal row.

Typical use is a round-trip: obtain spans with toLines, transform them (e.g. to highlight search matches), and reassemble with fromLine.

import Tui.Screen as Screen
import Tui.Screen.Advanced as Advanced


source : Screen.Screen
source =
    Screen.text "hello" |> Screen.bold


roundTripped : Screen.Screen
roundTripped =
    source
        |> Advanced.toLines
        |> List.head
        |> Maybe.withDefault []
        |> Advanced.fromLine

Reading a Style

Getters for the style field of a Span. The Style type from Tui.Screen is opaque so that future releases can add fields without breaking user code; these getters are the supported way to inspect it.

styleForeground : Style -> Maybe Color

Read the foreground color of a Style.

styleBackground : Style -> Maybe Color

Read the background color of a Style.

styleAttributes : Style -> List Attribute

Read the attribute list of a Style.

import Tui.Attribute as Attr
import Tui.Screen.Advanced as Advanced


if List.member Attr.Bold (Advanced.styleAttributes span.style) then
    ...

styleHyperlink : Style -> Maybe String

Read the hyperlink URL of a Style, if any.

Flat Style Records

For lower-level access, FlatStyle is a plain record with one Bool field per Tui.Attribute.Attribute plus the color/hyperlink fields. Conversion to/from a Style is provided for framework-level consumers that need to manipulate styles as records.

type alias FlatStyle =

FlatStyle

Flat record representation of a Style, with one Bool per attribute plus color and hyperlink fields.

styleToFlatStyle : Style -> FlatStyle

Convert an opaque Style to its flat record form.

flatStyleToStyle : FlatStyle -> Style

Convert a flat record back to an opaque Style. Inverse of styleToFlatStyle.

dillonkearns/elm-pages/12.3.0

Tui.Screen.Advanced

Lines

Rebuilding

Reading a Style

Flat Style Records

Modules