Term.jl

The Compositor allows you to define complex terminal layouts using Julia Expression syntax. Instead of manually nesting vstack, hstack, or grid with many placeholders, you define a layout template where placeholders are represented by single-character names followed by their dimensions (e.g., A(height, width)).

Key features:

• Placeholder Syntax: Use single characters (like A, B, C) to represent slots in the layout. Dimensions are passed as (height, width).
• Stacking Operators: Use standard stacking operators like * (horizontal/side-by-side) and / (vertical/stacked) within the expression.
• Fractional Sizing: To make elements responsive to terminal size, use Float64 values for dimensions. A value of 0.75 will occupy 75% of the available space.
• Interpolation: You can break down complex layouts by using Julia's interpolation ($) to compose smaller layout expressions into a larger one.

using Term.Compositors

# Simple layout with placeholders
layout = :(A(5, 45) * B(5, 45))
Compositor(layout)

# Responsive layout using fractional widths
layout_responsive = :(A(20, $(0.75)) * B(20, $(0.25)))
Compositor(layout_responsive)

# Complex layout using interpolation
first_column = :(vstack(A(5, 40), B(5, 40)))
second_column = :(vstack(F(5, 40), G(5, 40))
layout = :( ($first_column * E(20, 5) * $second_column) / O(5, 85) )
Compositor(layout)

To allow a widget to capture user input, you must define a controls attribute. This attribute is a dictionary that maps specific keys to handler functions. When a key is pressed while the widget is active, the corresponding function is executed.

Key Types

The dictionary keys can be one of two types:

1. Char: A single character (e.g., 'q', 'h', or ']').
2. KeyInput: Special keys such as ArrowLeft(), HomeKey(), EndKey(), Esc(), or SpaceBar().

Function Signature

Each handler function must follow the signature fn(w, k), where:

• w: The widget instance the function is assigned to.
• k: The key that was pressed.

Because a single function might handle multiple different keys (e.g., both ArrowRight() and ']' triggering a page down), the function signature should use a Union type to accommodate the possible key inputs.

# Example: Defining a handler that accepts multiple key types
next_page(p::Pager, ::Union{PageDownKey, ArrowRight, Char})

# Example: Mapping keys to handlers in the controls dictionary
pager_controls = Dict(
    ArrowRight() => next_page,
    ']' => next_page,
    ArrowLeft() => prev_page,
    '[' => prev_page,
    ArrowDown() => next_line,
    '.' => next_line,
    ArrowUp() => prev_line,
    ',' => prev_line,
    HomeKey() => home,
    EndKey() => toend,
    Esc() => quit,
    'q' => quit,
)

In Term.jl, complex terminal outputs are constructed using Renderables, which are subtypes of AbstractRenderable. Unlike simple styled strings, renderables allow you to create structured UI elements like panels, boxes, and trees.

Every renderable is composed of two fundamental components:

1. Segment: Represents a single line of text. A renderable is essentially a collection of segments that are printed sequentially, one per line, to create a single visual object.
2. Measure: Defines the dimensions (width and height) of the renderable as it will appear in the terminal. The Measure is used by the layout engine to position and combine multiple renderables.

Common renderable types include:

• Panel: Creates a bordered container around content.
• RenderableText: Handles text rendering within the console.
• TextBox: A hybrid between text and structured containers.
• Tree: For hierarchical data visualization.

import Term: Panel

# Example of a Panel with automatic fitting
print(Panel("this is {red}RED{/red}"; fit=true))

Layouts are defined using Julia Expr objects (syntax like :(...)). You specify the size and position of widgets using the pattern name(height, width).

• height: Must be an Int representing the number of lines.
• width: Can be an Int (number of columns) or a Float64 between 0 and 1 (representing a fraction of the available space).
• * operator: Places elements "to the side of" each other.
• / operator: Places elements "above" each other.

Using Float64 for width enables responsive layouts that resize when the terminal size changes. To allow the app to expand to fill the entire terminal when enlarged, use the expand keyword argument in the App constructor.

To visualize a layout without actual widgets, you can create an empty app with placeholders: App(layout) |> frame.

# Example: a is 10 lines high and half width, b is same, c is 10 lines high and full width, with c below a and b
layout = :( (a(10, .5) * b(10, .5)) / c(10, 1) )

# Example: single element taking 10 lines and 50% width
:r(10, 0.5)