Table of Contents

Canvas directives

Canvas directives position a child of a canvas layout by its distances to the edges of the canvas.

Warning

A canvas layout is only meant for elements that must overlap. Never use it, nor these directives, to lay out a screen or an area of a screen with fixed positions: use vertical-layout, horizontal-layout and grid-layout, which adapt to the content and to the window.

Top, Right, Bottom, Left

Gives the distance between an edge of the canvas and the same edge of the child.

Directive name: canvas:top, canvas:right, canvas:bottom, canvas:left

Values:

Value Example Meaning
Number 24, 12.5 A distance in pixels, without a unit. Decimals are allowed.
Negative number -8 The child goes past the edge of the canvas by this distance.
Percentage 30%, 33.33% A percentage of the canvas size: of its width for left and right, of its height for top and bottom.
Negative percentage -10% The child goes past the edge of the canvas by this percentage of the canvas size.
Bound value @Computeds.BadgeTop, $Item.Top A value computed by the page, in one of the formats above. An empty value removes the distance.

Any other value, such as 12px, auto or calc(100% - 16px), is rejected when the template is generated. As for the layout directives, a bound value or a constant is not checked.

Example:

<canvas-layout layout:width="320" layout:height="160">
  <badge value="New" canvas:top="8" canvas:right="8" />
  <text canvas:left="8" canvas:bottom="8">Bamboo watch</text>
</canvas-layout>

In this example, the badge sits 8 pixels from the top and right edges of the canvas, and the text 8 pixels from its left and bottom edges.

Result:

New
Bamboo watch

Two opposite distances on the same axis stretch the child between them: its size on that axis is given by the distances, and a layout:width or layout:height written next to them on that axis is a generation error. Write both distances at the same place, on the root element of the template of a UI component or on its usage: otherwise, a size of its own that the child has on that axis, such as the size of an image, wins over one of them.

<canvas-layout layout:width="320" layout:height="160">
  <text canvas:left="0" canvas:right="0" canvas:bottom="0">In stock</text>
  <vertical-layout style:background="primary-500" canvas:top="8" canvas:right="8" canvas:bottom="48" layout:width="40" />
</canvas-layout>

In this example, the text is as wide as the canvas, at its bottom, and the vertical layout goes from 8 pixels under the top edge to 48 pixels above the bottom edge.

Result:

In stock
Warning

These directives only apply to the direct children of a canvas-layout, or to the children of an if, if-not or repeat placed directly in it. Used anywhere else, they are ignored and the generation reports a warning. A repeat with virtual="true" is not allowed in a canvas-layout. On the root of a partial-template placed in a canvas, they are ignored too: wrap the partial template in an element that carries them (see Partial templates in a canvas).

Warning

A child cannot have both a distance and a layout:align-self-horizontal (for canvas:left and canvas:right) or a layout:align-self-vertical (for canvas:top and canvas:bottom): the generation reports an error. Both are only allowed when both are bound, and the page must then give a value to only one of them at a time.

The canvas layout page describes every use of these directives: percentages, negative distances, alignment, overflow, centering a child on a position with style:translate, bound and animated positions.

See also