Position, size, origin, rotation

Placing a component exactly where you want it.

pos and origin always go together

This is the point to understand before anything else, because the two do not talk about the same thing:

pos — where, on the SCREEN, the component is placed. origin — which point OF THE COMPONENT is placed at that spot.

One is a position on the screen, the other a point of the component. It is the meeting of the two that decides where the component appears.

pos — a position on the screen

<pos>0.1 0.2</pos>

These two numbers are measured from the screen's top-left corner: 0 0 is that corner, 1 1 the bottom-right corner.

The simplest is to read them as percentages — it is exactly the same thing: 0.1 = 10%, 0.2 = 20%, 0.5 = 50%. So pos 0.1 0.2 is 10% of the width and 20% of the height.

pos says nothing about the component itself: it is a mere point on the screen. What decides which part of the component lands there is origin.

origin — which point OF THE COMPONENT

origin answers the other half of the question: now that we know where on the screen, which part of the component comes to rest there?

These nine values are the most common, but any pair between 0 and 1 works:

By default, origin is 0 0 — the component's top-left corner. That is why a component without origin extends to the right and downward from its pos.

The example that makes it all click

Take a landscape image on a 16:9 screen:

<pos>0.5 0.5</pos>
<origin>1 1</origin>

pos 0.5 0.5 is the center of the screen. You might think the image will be centered there. It is not: origin 1 1 designates the image's bottom-right corner, and it is that corner which is placed at the center.

The image therefore ends up entirely above and to the left of the center.

To really center

<pos>0.5 0.5</pos>
<origin>0.5 0.5</origin>

This time it is the image's center that is placed at the screen's center.

The full table

What it is really for

Without origin, every component is placed by its top-left corner: to center something, you would have to compute 0.5 − width/2, and recompute every time the width changes.

With origin, you compute nothing anymore:

It is especially useful for a system logo, whose width changes from one machine to the next: with origin, it stays aligned no matter what.

size — the imposed size

<size>0.3 0.2</size>

The component is exactly that size. For an image, this means it is distorted to fill the box.

Give only one

Put 0 for the other: the missing dimension is computed to keep the proportions.

<size>0.3 0</size>   <!-- 30% wide, proportional height -->

⚠️ This is not the same as keepratio or maxSize, even though both keep proportions:

In other words: size with a zero imposes one constraint, maxSize imposes two.

maxSize — the maximum size, without distortion

<maxSize>0.3 0.2</maxSize>

The image is enlarged or reduced while keeping its proportions to fit in the box. It therefore rarely fills its whole surface.

For a system logo, maxSize is almost always what you want. Logos do not have the same shape from one machine to the next: with size, some would be squashed.

size together with keepratio gives the same result as maxSize — and it is often the preferred spelling, because it states the intended size instead of a limit:

<size>0.3 0.2</size>
<keepratio>true</keepratio>   <!-- ⚠️ all lowercase -->

maxSize only exists on image and video.

rotation and rotationOrigin

<rotation>90</rotation>
<rotationOrigin>0.5 0.5</rotationOrigin>

rotation is in degrees, clockwise. rotationOrigin designates the point around which the component pivots, in its own proportions. Without rotationOrigin, the pivot is the top-left corner (0 0) — write 0.5 0.5 to rotate around the center.

Rotation applies to images, color blocks, videos and Markdown blocks. A rotated text draws at small angles but disappears at 90°; a rotated scrolling text only draws its background, never its text. For a vertical title, go through an image or a Markdown block.

Depth (zIndex) and switching off (disabled) have their own page: Depth and visibility.