APL Data Types (APL 1.2 to 1.3)

APL supports a set of data types. You can use these data types when setting property values in your APL document. This document describes the APL data types in the latest version of APL.

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.

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 dimensions 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,360]. 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,360]. 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

Gradient

A gradient is a shaded color pattern for backgrounds and overlays. For example, you can set the overlayGradient property on an Image to apply a gradient scrim to the image.

A gradient is represented as an object with the following properties:

For example, a sample linear gradient for an image scrim might be:

{
  "type": "linear",
  "colorRange": [
    "white",
    "transparent"
  ],
  "inputRange": [
    0,
    0.5
  ]
}

In the above example, the bottom of the gradient is white. The gradient linearly transitions to transparent at 50% of the way up, and then remains transparent across the rest of the drawing area.

angle

The angle of a linear gradient, measured in degrees clockwise from vertical. 0 is up, 90 is to the right, 180 is down, and 270 is to the left. The angle can be any value; the actual drawing is modulo 360.

colorRange

The color to assign at each gradient stop. Colors are linearly interpolated between stops.

inputRange

The inputRange specifies the position of the gradient stops. If the inputRange is not specified, the first color value is at gradient stop 0, the last at gradient stop 1, and the others spread evenly between 0 and 1.

type

There are two types of gradients: linear and radial. Linear gradients start at one corner or side (depending on angle) and extend to the other corner/side. Radial gradients are always positioned at the center and the farthest corner has the final color stop. Radial gradients are not circular; they are elliptical based on the shape of the surrounding container.

Filter

A filter is an image-processing operation applied against a bitmap image. For example:

{
  "type": "Image",
  "filters": [
    {
      "type": "Blur",
      "radius": "10dp"
    },
    {
      "type": "Noise",
      "sigma": 20
    }
  ]
}

Each filter has a type property that indicates the type of filter to apply. Filters are applied in the order they are defined.

Blur

Apply a Gaussian blur with a specified radius.

Noise

Add generated noise to the image.

Generated noise is added to each pixel in the image. The kind property sets the probability distribution to use. Turning the useColor property to true treats the red, green, and blue channels of the image separately.

The sigma property sets the standard deviation of the noise on the color pixels. Each color pixel falls in the range [0,255], so a sigma of 10 means that on average the pixel will vary from its original value by 10. In practice the sigma property is commonly set between 5 and 50.

Last updated: Nov 28, 2023