APL Data Types

This section defines a number of common data types.

Dimension

Dimensions in APL can be expressed in three different ways: Absolute, relative, and special.

Absolute dimensions

Absolute dimensions are integers interpreted as display-independent pixels. Absolute dimensions can also be expressed as a string with a unit suffix. The unit suffix must immediately follow the dimension. The valid suffixes are listed below.

Suffix Description Example
dp Display-independent pixels 20dp
px Screen pixels 10px
vh Viewport height, where 100 is the full viewport height. 1 vh is 1% of the viewport height. 50vh
vw Viewport width, where 100 is the full viewport width. 1 vw is 1% of the viewport width. 33vw

Relative dimensions

Relative dimensions are represented by a string of the form "X%", where X is a valid JSON number. A percentage dimension is interpreted as a percentage of the containing component bounding box. Since the bounding box has two dimensions (width and height), the appropriate dimension will be chosen if the semantic of the property is inherently horizontal or vertical (such as height). If the property has no clear direction (such as borderRadiusTopRight), a percentage of the bounding box width will be used.

Relative dimensions are not supported for the padding properties on all components.

Note that percentage dimensions can create a dependency loop, in which case the results are undefined. For example, if the parent container has auto sizing and the child's height is set to "50%", the result is undefined.

Special dimensions

Special dimensions are named values that have special processing. The only current special defined is "auto", which means that the component size should match its natural size. For example, a Text component with width and height set to "auto" will be laid out in a single line in a bounding box that exactly contains the text.

Special dimensinos are not supported for the Image component width and height properties.

Color

Color values are strings converted internally to a valid R,G,B,A tuple. The grammar is as follows:

color         ::= _ <<basecolor>> _
<<basecolor>> ::= <<hex>> | <<function>> "(" _ <<args>> _ ")" | <<symbol>>
<<hex>>       ::= "#" [0-9a-fA-F]{3,4,6,8}
<<symbol>>    ::= [a-zA-Z]+
<<function>>  ::= "rgb" "a"? | "hsl" "a"?
<<args>>      ::= <<arg>> ( "," _ ARG )*
<<arg>>       ::= <<basecolor>> | <<percent>> | <<number>>
<<percent>>   ::= <<number>> "%"
<<number>>    ::= [0-9]+ "." [0-9]* | "." [0-9]+ | [0-9]+
_             ::= [ \t\n\r]*

Standard colors

A standard color is a named reference from the HTML standard. For example: "azure", "burlywood", "red".

Hexadecimal color

A color may be defined as a #-prefixed hexadecimal string. The string may be of the following forms:

  • #RGB
  • #RGBA
  • #RRGGBB
  • #RRGGBBAA

RGB / RGBA function

A color may be defined as an rgb() or rgba() function (the second is an alias for the first). These are interpreted in different ways depending on the number of arguments:

  • Two arguments: The first argument is a color and the second argument is an alpha value to apply to the color. For example, rgba(red,0.2) would give the color red at 20% opacity.

  • Three arguments: The arguments are R, G, and B (each an integer in the range [0,255]). The alpha level is set to 1.0. For example, rgba(0,255,0) is equivalent to "#00FF00FF".

  • Four arguments: The arguments are R, G, B, and A. The R/G/B values are integers in the range [0,255]. The A value is a number in the range [0,1].

HSL / HSLA function

A color may be defined as an hsl() or hsla() function (the second is an alias for the first). These are interpreted depending on the number of arguments:

  • Three arguments: The H argument (hue) is an integer in the range [0,255]. The S (saturation) and L (lightness) arguments are numbers in the range [0,1]. The A (alpha) value is set to 1. For example, hsl(0, 100%, 50%) is "red".

  • Four arguments: The H argument (hue) is an integer in the range [0,255]. The S (saturation), L (lightness), and A (alpha) arguments are numbers in the range [0,1]. For example, hsla(120, 1, .25, 25%) equals rgb(darkgreen, 0.25).

Transparent

A color may be defined as the keyword "transparent". This is a shortcut for rgba(0,0,0,0).

Data-binding lookup

Color expressions are not defined inside of data-binding expressions. For example, the following expression will not work.

   "color": "${ rgba(0, 0, 255, 20%) }" // INCORRECT!

Instead, write your data-binding logic to evaluate only the pieces of the string that involve calculation or resource lookup:

"color": "rgba(0,0,255,20%)" // CORRECT