@vertigis/viewer-spec/docs/presentation.md

VertiGIS Viewer Specification

# Presentation

This document describes the syntax and semantics for presentation attributes:

-   Margin
-   Padding
-   Width
-   Height
-   Grow
-   Horizontal alignment
-   Vertical alignment

## Applicability

All attributes apply to all components unless otherwise stated.

## Units

All dimensional units are expressed in 'em's, unless specified otherwise, where 1 em is equal to the current font size.

## Margin

**Attribute name**: "margin".  
**Expected value**: Either 0 or a positive number (integer or floating point).  
**Description**: Sets the size of the white space outside of the component.

**Example**:

```
<map margin="1.5"/> <!-- Sets the margin on a map to be equal to 1.5x the current font size -->
```

## Padding

**Attribute name**: "padding".  
**Expected value**: Either 0 or a positive number (integer or floating point).  
**Description**: Sets the size of the white space between a component and its content.  
**Applies to**: In VertiGIS Studio Mobile, this attribute will only apply to components with children, due to technical restrictions.

**Example**:

```
<stack padding="0.5"/> <!-- Sets the padding on a stack to be equal to 0.5x the current font size -->
```

## Width and Height

**Attribute name**: "width".  
**Expected value**: Em units: Either 0 or a positive number (integer or floating point). Example: 12.

**Default value**: If a width is not set, then the width shall be the natural width of the component (however much space it needs).  
**Description**: Sets the width of a component. If em units, then the width is a literal value.

**Attribute name**: "height".  
**Expected value**: Em units: Either 0 or a positive number (integer or floating point). Example: 12.

**Description**: Sets the height of a component. If em units, then the height is a literal value.

**Example**:

```
<!-- Sets the width of a map to 30em, and the height to 20em. -->
<map width="30em" height="20"/>
```

## Grow

**Attribute name**: "grow".  
**Expected value**: Either 0 or a positive number (integer or floating point).  
**Description**: Sets whether or not a component's width or height will grow over its parents primary axis. Components with a grow of 0 will fill to their natural or requested height. Components with a specified grow will fill up a percentage of the remaining space equal to their grow value divided by the total grow of all sibling components (including the component in question).  
The default value for a component varies by component. For most components, if no grow value is specified, they will default to a grow value of "0". The following components however will have a default grow value of "1":

-   Map
-   Stack
-   Split

**Applies to**: All components may specify this value, but it will only take effect if the component is a child of a split or a stack. For stacks, grow indicates how the child grows along the vertical axis. For splits, grow indicates how the child grows along the horizontal axis.

**Example**:

```
<stack>
    <!-- Heading will take up whatever vertical space it requires, and will occupy its natural width. -->
    <text content="Heading"/>
    <!-- The first map will occupy 1/3 of the remaining vertical space, and will occupy the full width available. -->
    <map grow="1"/>
    <!-- The first map will occupy 2/3 of the remaining vertical space, and will occupy the full width available. -->
    <map grow="2"/>
</stack>
```

## Alignment

**Attribute name**: "halign".  
**Expected value**: One of: "start", "center", or "end"  
**Description**: Describes how the content of a component is aligned. For stacks and splits, the content is the child components. For a component like text, the content is the text itself.

**Attribute name**: "valign".  
**Expected value**: One of: "start", "center", or "end"  
**Description**: Describes how the content of a component is aligned. For stacks and splits, the content is the child components. For a component like text, the content is the text itself.

### Effect on cross-axis stretching

All components will stretch across the cross-axis if the corresponding alignment attribute (halign for stacks, valign for splits) is not set on the parent of that componet. But if a cross-axis alignment is set, then they will no longer stretch across the cross axis (otherwise the effect of alignment would not be observed).  
Some components will stretch across the cross-axis even if the cross-axis alignment is set on the parent: map, stack, split.