line

Function

line(
    states: list[State],
    spacing: float = 100,
    rotation: float = 0,
    center: Point2D = Point2D(x=0, y=0),
    distances: Optional[List[float]] = None,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0
) -> list[State]

Arrange states in a straight line formation.

Positions elements along a straight line with configurable spacing, rotation, and center point. For odd numbers of elements, one element is placed at the center. For even numbers, elements are distributed symmetrically around the center point. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x and y positions.

Parameters

states: List of states to arrange
spacing: Distance between adjacent elements. Only used when distances is None.
rotation: Angle of the line in degrees (0° = horizontal right, 90° = vertical down)
cx: X coordinate of line center
cy: Y coordinate of line center
distances: Optional list of specific distances from center for each element. If provided, overrides automatic distribution and spacing parameter. Positive values = forward along line, negative = backward along line. List length should match states length.
alignment: How to align each element relative to the line. PRESERVE keeps original rotation, LAYOUT aligns parallel to line, UPRIGHT starts from vertical position.
element_rotation_offset: Additional rotation in degrees added to the alignment base.

Returns

New list of states with line positions

Examples

# Even spacing (automatic distribution)
    line_layout(states, spacing=50, rotation=0)

    # Explicit distances from center
    line_layout(states, distances=[-100, -20, 50, 150])

    # Mixed: some bunched together, others spread out
    line_layout(states, distances=[-50, -45, 0, 100, 200])

    # Elements aligned with line direction
    line_layout(states, rotation=45, element_rotation_offset=ElementRotation.ALIGN)

    # Elements kept upright regardless of line rotation
    line_layout(states, rotation=45, element_rotation_offset=ElementRotation.UPRIGHT)

    # Elements upside down (useful for text hanging from a line)
    line_layout(states, element_rotation_offset=ElementRotation.HEADS_DOWN)

    # Elements aligned opposite to line direction (pointing backward)
    line_layout(states, rotation=45, element_rotation_offset=ElementRotation.ALIGN_REVERSE)