Layout

A Layout divides a screen into regions. Each region is a rectangle in fractions of the screen and a label selector, and it shows the window of the first pod whose labels match. A Display names the Layout it shows in spec.layout, and a Display that names none shows every window fullscreen with the newest on top. The guide walks through a two-region screen with pods from two namespaces.

The order of spec.regions is the stacking order, last on top. The pods never learn where they are drawn: the Layout is the only place the arrangement lives, so a moved region moves every screen that names the Layout and changes no pod.

The regions of a screen. Each region is a rectangle in fractions of the screen and a label selector that chooses the pod whose window it shows. A Display names a Layout in spec.layout, and one Layout can apply to any number of screens.

spec

The regions, in stacking order.

Field Type Required Description
regions []object yes The screen’s regions in stacking order. A region written after another draws over it where they overlap. Each region shows one program: the first claim to arrive whose holders’ labels match the selector. Every window of that claim is drawn in the region, newest on top. The Display’s status.layout reports the window on top.

spec.regions[]

The screen’s regions in stacking order. A region written after another draws over it where they overlap. Each region shows one program: the first claim to arrive whose holders’ labels match the selector. Every window of that claim is drawn in the region, newest on top. The Display’s status.layout reports the window on top.

Field Type Required Description
name string yes The region’s name, unique in this Layout. The Display’s status.layout reports it beside the surface the region shows, and status.surfaces names it on the surface. Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
rect object yes The region’s rectangle, as four fractions of the screen, so one Layout fits a 1080p panel and a 4K one. The compositor tells the window its rectangle’s size in pixels, and the program redraws at that size.
selector object yes Which pod’s window the region shows, as a label selector over pods that hold a claim on this screen, like a Service selector. Any label counts. Candidates are only pods that hold a claim on this screen, so a matching label elsewhere in the cluster matches nothing here. A window on the shared socket belongs to no claim and matches no selector.
transition object no How a window enters and leaves the region. The compositor draws both transitions, because the program does not know its region. Both halves are optional. An absent half makes the window enter or leave at once.

spec.regions[].rect

The region’s rectangle, as four fractions of the screen, so one Layout fits a 1080p panel and a 4K one. The compositor tells the window its rectangle’s size in pixels, and the program redraws at that size.

Field Type Required Description
left number yes The left edge, as a fraction of the screen’s width. 0 is the left edge of the screen.
top number yes The top edge, as a fraction of the screen’s height. 0 is the top of the screen.
width number yes The width, as a fraction of the screen’s width. left plus width is at most 1.
height number yes The height, as a fraction of the screen’s height. top plus height is at most 1.

spec.regions[].selector

Which pod’s window the region shows, as a label selector over pods that hold a claim on this screen, like a Service selector. Any label counts. Candidates are only pods that hold a claim on this screen, so a matching label elsewhere in the cluster matches nothing here. A window on the shared socket belongs to no claim and matches no selector.

Field Type Required Description
matchLabels map[string]string no Labels the pod carries with exactly these values. Every entry must match.
matchExpressions []object no Requirements on the pod’s labels. Every requirement must hold, and they combine with matchLabels.

spec.regions[].selector.matchExpressions[]

Requirements on the pod’s labels. Every requirement must hold, and they combine with matchLabels.

Field Type Required Description
key string yes The label key the requirement reads.
operator string yes How the key is judged: In and NotIn compare its value against values, and Exists and DoesNotExist ask only whether the key is present. One of: In, NotIn, Exists, DoesNotExist.
values []string no The values In and NotIn compare against. Exists and DoesNotExist take none.

spec.regions[].transition

How a window enters and leaves the region. The compositor draws both transitions, because the program does not know its region. Both halves are optional. An absent half makes the window enter or leave at once.

Field Type Required Description
enter object no How a window enters the region. It runs when a window arrives in the region, whether the pod is new or its labels started matching.
exit object no How a window leaves the region. The transition runs when a still-drawing window stops matching the region, such as after a controller removes a label. A program that ends takes its window with it. A window the compositor no longer holds leaves at once, whatever this field states.

spec.regions[].transition.enter

How a window enters the region. It runs when a window arrives in the region, whether the pod is new or its labels started matching.

Field Type Required Description
kind string yes none shows the window at once. fade brings it from transparent to opaque over milliseconds. One of: none, fade.
milliseconds integer no How long the entrance runs. 0 is the same as none.

spec.regions[].transition.exit

How a window leaves the region. The transition runs when a still-drawing window stops matching the region, such as after a controller removes a label. A program that ends takes its window with it. A window the compositor no longer holds leaves at once, whatever this field states.

Field Type Required Description
kind string yes none takes the window off at once. fade brings it from opaque to transparent over milliseconds, and the program keeps drawing until the fade ends. One of: none, fade.
milliseconds integer no How long the exit runs. 0 is the same as none.