# `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](/docs/guides/layout/) 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](#specregions) | 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](#specregionsrect) | 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](#specregionsselector) | 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](#specregionstransition) | 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](#specregionsselectormatchexpressions) | 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](#specregionstransitionenter) | 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](#specregionstransitionexit) | 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. |