TermKit Documentation

A ColorScheme defines the visual appearance of a view across different states. You create a custom scheme by instantiating ColorScheme() and assigning Attribute objects to its state properties.

Key properties of ColorScheme:

• normal: Default appearance.
• focus: When the view has focus.
• hotNormal: Appearance of hotkey characters when the view is not focused.
• hotFocus: Appearance of hotkey characters when the view is focused.
• disabled: When the view is disabled.

let scheme = ColorScheme()
scheme.normal = Application.makeAttribute(fore: .white, back: .blue)
scheme.focus = Application.makeAttribute(fore: .black, back: .cyan)
scheme.hotNormal = Application.makeAttribute(fore: .yellow, back: .blue)
scheme.hotFocus = Application.makeAttribute(fore: .yellow, back: .cyan)
scheme.disabled = Application.makeAttribute(fore: .brightBlack, back: .blue)

When building cross-platform UIs, be aware of varying terminal capabilities regarding colors and text decorations.

Color Support

• Standard Colors: 16 standard colors (e.g., .white, .blue) are safe and work everywhere.
• Bright Colors: Most modern terminals support bright variants (e.g., .brightWhite, .brightBlue).

Cell Flags

• Universal Support: CellFlags.bold, CellFlags.underline, and CellFlags.inverse are widely supported.
• Variable Support: CellFlags.italic and CellFlags.strikethrough may not render on all terminals. CellFlags.blink is often disabled by terminal emulators.

// Safe: 16 standard colors work everywhere
let safeAttr = Application.makeAttribute(
    fore: .white,
    back: .blue
)

// Bright colors: most terminals
let brightAttr = Application.makeAttribute(
    fore: .brightWhite,
    back: .brightBlue
)

TermKit is not thread-safe. All modifications to views and UI state must be performed on the main queue using Grand Central Dispatch (GCD). The main event loop integrates with dispatchMain().

DispatchQueue.main.async {
    // Safe to modify views here
    label.text = "Updated"
}

Each view manages its own coordinate system using three primary properties:

• frame: The position and size relative to the superview.
• bounds: The view's own rectangle, which is always at origin (0, 0).
• contentFrame: The specific area available for content, excluding borders and padding.

TermKit uses a specific set of types to handle positioning and sizing within the terminal:

• Pos: Used for positioning elements (e.g., Pos.center()).
• Dim: Used for defining dimensions.
• Rect: Defines a rectangular area.
• Point: Represents a specific coordinate.
• Size: Represents width and height.

TermKit supports several common UI layout patterns:

Form Section

Use a Frame with Dim.fill() for width to group related input fields like labels and text fields.

Master-Detail

Use a SplitView (usually .horizontal) with a ListView in one panel and a Frame (the detail view) in the other.

Tabbed Preferences

Use a TabView to organize settings into logical groups like "General" and "Advanced".

// Master-Detail Pattern Example
let split = SplitView()
split.orientation = .horizontal
split.position = 0.3

let masterList = ListView(items: items)
let detailView = Frame("Details")

split.addArrangedSubview(masterList)
split.addArrangedSubview(detailView)

The Painter class is the primary API for custom drawing in TermKit. You access it when overriding drawContent(in:painter:) or redraw within a View. It provides methods for positioning the cursor, adding text, drawing lines, shapes, and managing colors via attributes.

override func drawContent(in region: Rect, painter: Painter) {
    // Draw using painter
}

Buttons support hotkeys via the Alt key. The first uppercase letter in the label, or the character following an underscore, becomes the hotkey.

• Button("_Save") -> Alt+S activates.
• Button("Save") -> Alt+S activates.

let button = Button("_Save")  // Alt+S activates
let button = Button("Save")   // Alt+S also works (first letter)

TermKit's architecture is built around several fundamental classes that manage the application lifecycle and view hierarchy:

• Application: The central entry point used to prepare the environment (prepare()), access the top-level view (top), and start the execution loop (run()).
• View: The base class for all UI elements, supporting nested subviews.
• Toplevel: Represents the highest level in the view hierarchy.
• Window: A container for views, typically representing a distinct UI area.
• Responder: The base class for handling input events through a responder chain.

TermKit applications support standard terminal-based keyboard navigation:

• Tab / Shift+Tab: Cycle focus between different controls.
• Enter: Activate the currently focused control (e.g., trigger a Button.clicked event).
• Typing: Enter text into a focused TextField.
• Ctrl+C: Emergency exit from the application.