gh-ypares-agent-skills-ypares-agent-skills/skills/textual-builder/references/layout.md

Layout and Positioning

Layout Types

Vertical (Default)

Stacks widgets vertically:

Container {
    layout: vertical;
}

Horizontal

Arranges widgets side-by-side:

Container {
    layout: horizontal;
}

Grid

Grid layout with rows and columns:

Grid {
    layout: grid;
    grid-size: 3 2;  /* 3 columns, 2 rows */
    grid-gutter: 1 2;  /* vertical horizontal spacing */
}

Grid Cell Spanning

Make widgets span multiple cells:

#header {
    column-span: 3;  /* Span 3 columns */
}

#sidebar {
    row-span: 2;     /* Span 2 rows */
}

Grid Rows and Columns

Define row heights and column widths:

Grid {
    grid-size: 2 3;
    grid-rows: 1fr 6 25%;     /* Flexible, fixed 6, 25% */
    grid-columns: 1fr 2fr;    /* 1:2 ratio */
}

Alignment

Screen/Container Alignment

Center content within screen:

Screen {
    align: center middle;  /* horizontal vertical */
}

Options: left, center, right × top, middle, bottom

Content Alignment

Align content within a widget:

MyWidget {
    content-align: center middle;
    text-align: center;
}

Docking

Pin widgets to screen edges:

#header {
    dock: top;
    height: 3;
}

#sidebar {
    dock: left;
    width: 20;
}

#footer {
    dock: bottom;
}

Docking order matters - earlier docked widgets take priority.

Sizing

Fixed Sizes

Widget {
    width: 50;      /* 50 cells */
    height: 10;     /* 10 rows */
}

Relative Sizes

Widget {
    width: 50%;     /* 50% of parent */
    height: 100%;
}

Fractional Units

Share available space proportionally:

#left {
    width: 1fr;     /* Gets 1 part */
}

#right {
    width: 2fr;     /* Gets 2 parts (twice as wide) */
}

Auto Sizing

Fit content:

Widget {
    width: auto;
    height: auto;
}

Min/Max Constraints

Widget {
    min-width: 20;
    max-width: 80;
    min-height: 5;
    max-height: 30;
}

Spacing

Margin

Space outside widget border:

Widget {
    margin: 1;          /* All sides */
    margin: 1 2;        /* vertical horizontal */
    margin: 1 2 3 4;    /* top right bottom left */
}

Padding

Space inside widget border:

Widget {
    padding: 1;         /* All sides */
    padding: 1 2;       /* vertical horizontal */
}

Visibility

Display

Show or hide widgets:

#hidden {
    display: none;
}

#visible {
    display: block;
}

Toggle in Python:

widget.display = False  # Hide
widget.display = True   # Show

Visibility

Similar to display but reserves space:

Widget {
    visibility: hidden;  /* Hidden but takes space */
    visibility: visible;
}

Layers

Control stacking order:

#background {
    layer: below;
}

#popup {
    layer: above;
}

Scrolling

Enable Scrolling

Container {
    overflow-x: auto;  /* Horizontal scrolling */
    overflow-y: auto;  /* Vertical scrolling */
    overflow: auto auto;  /* Both */
}

Programmatic Scrolling

# Scroll to specific position
container.scroll_to(x=0, y=100)

# Scroll widget into view
widget.scroll_visible()

# Scroll to end
self.screen.scroll_end(animate=True)

Example: Card Game Layout

Screen {
    layout: vertical;
}

#opponent-hand {
    dock: top;
    height: 12;
    layout: horizontal;
    align: center top;
}

#play-area {
    height: 1fr;
    layout: grid;
    grid-size: 5 3;
    align: center middle;
}

#player-hand {
    dock: bottom;
    height: 15;
    layout: horizontal;
    align: center bottom;
    padding: 1;
}

.card {
    width: 12;
    height: 10;
    margin: 0 1;
}