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 displayindependent 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  Displayindependent 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 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>> ::= "#" [09afAF]{3,4,6,8}
<<symbol>> ::= [azAZ]+
<<function>> ::= "rgb" "a"?  "hsl" "a"?
<<args>> ::= <<arg>> ( "," _ ARG )*
<<arg>> ::= <<basecolor>>  <<percent>>  <<number>>
<<percent>> ::= <<number>> "%"
<<number>> ::= [09]+ "." [09]*  "." [09]+  [09]+
_ ::= [ \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).
Databinding lookup
Color expressions are not defined inside of databinding expressions. For example, the following expression will not work.
"color": "${ rgba(0, 0, 255, 20%) }" //INCORRECT!
Instead, write your databinding 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:
Property  Type  Default  Description 

angle 
Number  0  Angle of a linear gradient, in degrees. 0 is up, 90 is to the right. 
colorRange 
Array of Color  REQUIRED  The color to assign at each gradient stop. 
description 
String  ""  Optional description of this gradient. 
inputRange 
Array of Number  []  The input stops of the gradient. Must be in ascending order with values between 0 and 1. 
type 
linear , radial 
linear 
The type of the gradient. 
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 singlevalued 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 timebased easing curves for animating the motion of a single property. For example:
{
"type": "AnimateItem",
"description": "Fade out the component",
"componentId": "TargetComponent",
"duration": 1000,
"easing": "cubicbezier(0.5,0.1,1,1)"
"value": {
"property": "opacity",
"to": 0
}
}
Easing functions may also be used to create timebased animations. For example, to change the background of a frame continuously:
{
"type": "APL",
"version": "2023.3",
"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:

cubicbezier(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*(1t)^2 + 3*x2*t^2*(1t) + t^3 y(t) = 3*y1*t*(1t)^2 + 3*y2*t^2*(1t) + t^3
Note that the cubic Bézier defines
x
andy
as a function oft
. To calculatey(x)
, the input value ofx
is used to findt
which is then used to calculatey
. 
path(x1,y1,...,xN,yN)
: A linearpiecewise 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 predefined:
Name  Equal to 

linear  path() 
ease  cubicbezier(0.25, 0.10, 0.25, 1.00) 
easein  cubicbezier(0.42, 0.00, 1.00, 1.00) 
easeout  cubicbezier(0.00, 0.00, 0.58, 1.00) 
easeinout  cubicbezier(0.42, 0.00, 0.58, 1.00) 
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 oft
(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 pointsa,b,c,d
. The control points should be values between 0 and 1. The interpolated values as a function oft
(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*(1t)^2 + 3*p2*t^2*(1t) + 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 ad 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": "2023.3",
"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 xcoordinate and one for the ycoordinate. 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 nonlinear; 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"  "easein"  "easeout"  "easeinout"
path ::= "path" "(" coords ("," coords)* ")"
cubicbezier ::= "cubicbezier" "(" 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 floatingpoint values. The syntax VALUE\_{DOF}
syntax is a set of DOF
floatingpoint values separated by commas.
Last updated: Nov 28, 2023