APL Data Types

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.

Easing function

An easing function is a continuous single-valued mathematical function that maps from a numeric input value (usually time) to a numeric output value. This document uses the term "easing function" because in computer programming, the term "function" has a different, more generalized meaning.

Easing functions are used in the AnimateItem command to define custom time-based easing curves for animating the motion of a single property. For example:

{
  "type": "AnimateItem",
  "description": "Fade out the component",
  "componentId": "TargetComponent",
  "duration": 1000,
  "easing": "cubic-bezier(0.5,0.1,1,1)"
  "value": {
    "property": "opacity",
    "to": 0
  }
}

Easing functions may also be used to create time-based animations. For example, to change the background of a frame continuously:

{
  "type": "APL",
  "version": "2024.2",
  "resources": [
    {
      "easing": {
        "ease1": "line(0,0) line(500,255) end(1000,0)",
        "ease2": "line(0,255) line(500,255) line(700,0) end(800,255)"
      }
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "TouchWrapper",
      "items": {
        "type": "Frame",
        "width": "100%",
        "height": "100%",
        "bind": {
          "name": "t",
          "value": "${elapsedTime % 1000}"
        },
        "backgroundColor": "rgb(${@ease1(t)},${@ease2(t)},0)"
      }
    }
  }
}

By convention, this document refers to the input value of the easing function as x. The output value is a function of x called y. Note that a common mistake is assuming that time is always the input of an easing function; there is no such requirement. An easing function is a continuous mathematical function that can be used however you like.

The easing grammar provides three basic ways of defining easing curves:

• Simple easing functions designed to be used with the AnimateItem command. These map input values from 0 to 1 into output values 0 to 1.
• Piecewise easing functions of straight lines and bezier curves that map arbitrary input values into arbitrary output values.
• Spatial easing functions that map position along a path defined in two or three dimensions.

Simple easing functions

Simple easing functions are designed to be used by the AnimateItem command. The easing function always starts at (0,0) and ends at (1,1). Two standard general ways of writing an easing curve are defined:

• cubic-bezier(x1,y1,x2,y2): Following the CSS standard, this defines a cubic Bézier curve with starting point (0,0) and ending point (1,0). The parameterized values (x1, y1) and (x2, y2) defined the interior control points of the curve and are normally between 0 and 1. The functions are defined as:

  x(t) = 3*x1*t*(1-t)^2 + 3*x2*t^2*(1-t) + t^3
  y(t) = 3*y1*t*(1-t)^2 + 3*y2*t^2*(1-t) + t^3
  

  Note that the cubic Bézier defines x and y as a function of t. To calculate y(x), the input value of x is used to find t which is then used to calculate y.

• path(x1,y1,...,xN,yN): A linear-piecewise function from (0,0) to (1,1). The x values must be in ascending order and between 0 and 1; the y values may be arbitrary. The end values of (0,0) and (1,1) are implicit.

The following easing curves are pre-defined:

Piecewise easing functions

Piecewise easing functions map from arbitrary input values to arbitrary output values. A piecewise easing function is defined by stringing together linear and cubic line segments. Each segment defines the starting coordinates of the segment. The final segment must be the "end" segment which defines the ending coordinates. The elements are:

• line(x,y): A straight line starting at the coordinates (x,y). The straight line ends at the coordinates of the next segment. The interpolated values as a function of t (where t varies from 0 to 1) are:

  x(t) = x1(t) + (x2(t) - x1(t)) * t
  y(t) = y1(t) + (y2(t) - y1(t)) * t
  

  This interpolates from the current coordinates (x1, y1) to the coordinates of the next segment (x2, y2).

• curve(x,y,a,b,c,d): A cubic spline starting at the coordinates (x,y) using the control points a,b,c,d. The control points should be values between 0 and 1. The interpolated values as a function of t (where t varies from 0 to 1) are:

  x(t) = x1(t) + (x2(t) - x1(t)) * f(a,c,t)
  y(t) = y1(t) + (y2(t) - y1(t)) * f(b,d,t)
  f(p1,p2,t) = 3*p1*t*(1-t)^2 + 3*p2*t^2*(1-t) + t^3
  

  This interpolates from the current coordinates (x1, y1) to the coordinates of the next segment (x2, y2).

• end(x,y): Must be the last point.

The easing function is considered to be "flat" before the first point and after the last point; for example, if the last point is end(10,100), then the function will return 100 for any input greater than 10.

Spatial easing functions

Spatial easing functions are useful when defining how a component will moving through space in N dimensions (usually 2 or 3). Each point in the spatial curve has a time and a tuple of coordinates. Each curve segment in a spatial curve has input and output relative control points which create the shape of the curve. The distance along the spatial curve is defined by a cubic easing function for each curve segment.

Intrinsically spatial curves map from a single input value to N output values. Because easing functions only support a single output value the first element of the spatial curve defines which of the N output values will be used. The elements of a spatial easing curve are:

• spatial(dof, index): Defines the start of a spatial easing function with dof degrees of freedom (usually 2 or 3) and using index to select the output value.
• scurve(x, y+, tout+, tin+, a, b, c, d): A cubic spline starting in space with the input parameter x and the spatial coordinates y+. The relative position of the spline control points from y+ is given by the tout+ values ("tangent out"). The ending point of the spline is given by the next segment. The relative position of the spline control points from the next segment is given by the tin+ values ("tangent in"). The control points a-d define how the x value is interpolated between the starting value and the ending value (given by the next segment).
• send(x, y+): Defines the last segment in the spatial easing function.

An example of a spatial easing function will help clarify how it works:

{
  "type": "APL",
  "version": "2024.2",
  "resources": {
    "strings": {
      "PATH": "scurve(0, 0,0, 100,0, 0,50, 0.2,0.0, 0.6,0.6)",
      "PATH2": "scurve(50, 100,100, 0,100, 0,50, 0.2,0.2, 0.6,0)",
      "PATH3": "send(1000, 0, 0)"
    },
    "easing": {
      "FX": "spatial(2,0) ${@PATH} ${@PATH2} ${@PATH3}",
      "FY": "spatial(2,1) ${@PATH} ${@PATH2} ${@PATH3}"
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Frame",
      "width": 20,
      "height": 20,
      "backgroundColor": "red",
      "bind": {
        "name": "t",
        "value": "${elapsedTime % 1000}"
      },
      "transform": {
        "translateX": "${@FX(t)}",
        "translateY": "${@FY(t)}"
      }
    }
  }
}

In this example a small red box (the frame) is animated continuously between (0,0) and (100,100). Two easing functions are used: one for the x-coordinate and one for the y-coordinate. The same spatial path is used for both easing functions with an appropriate spatial header to pull out the X and Y coordinates from the function. Note that the control points for time interpolation are non-linear; the red box "jumps" off from the (0,0) point, slows down as it comes near to (100,100) and then gradually begins to rise back with rapid acceleration as it gets near (0,0).

The following example shows this animation. The example adds a TouchWrapper to activate the animation. Click the Start Animation text on the viewport to see the animation.

Easing grammar

The easing grammar is defined as:

easing          ::= predefined | path | cubicbezier | segmented | spatialcurve
predefined      ::= "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out"
path            ::= "path" "(" coords ("," coords)* ")"
cubicbezier     ::= "cubic-bezier" "(" controlpoints ")"
segmented       ::= ( line | curve )+ end
line            ::= "line" "(" coords ")"
curve           ::= "curve" "(" coords "," controlpoints ")"
end             ::= "end" "(" coords ")"
spatialcurve    ::= spatial ( scurve )+ send
spatial         ::= "spatial" "(" DOF "," INDEX ")"
scurve          ::= "scurve" "(" X "," Y_{DOF} "," TOUT_{DOF} "," TIN_{DOF} "," controlpoints ")"
send            ::= "send" "(" X "," Y_{DOF} ")"
coords          ::= X "," Y
controlpoints   ::= A "," B "," C "," D

The individual elements A, B, C, D, X, and Y are floating-point values. The syntax VALUE\_{DOF} syntax is a set of DOF floating-point values separated by commas.

Last updated: Nov 28, 2023