Alexa Vector Graphics Format

Use the Alexa Vector Graphics (AVG) format to define vector graphics for use in APL documents. AVG is a parameterized subset of scalable vector graphics (SVG) selected to be portable to multiple operating systems. You can display an AVG-defined graphic with the VectorGraphic component. The VectorGraphic component can load an AVG object from an APL package, APL document, or URL.

AVG object properties

The following table shows the properties of an AVG object.

Property Type Default Description
data Array none Data to bind into the child items.
description String "" Optional description of this vector graphic.
height Positive absolute Dimension REQUIRED The height of the graphic.
item, items Array of AVG items [] An array of drawing items. Each item is a group, path, or text.
parameters Array of AVG parameters [] An array of parameter values that can be set on the AVG object.
resources RESOURCES [] Local graphic-specific resources
scaleTypeHeight none | grow | shrink | stretch none How the viewport height changes as the height scales.
scaleTypeWidth none | grow | shrink | stretch none How the viewport width changes as the width scales.
styles STYLES {} Local graphic-specific styles
type "AVG" REQUIRED The type of vector graphic.
version 1.2 REQUIRED The current release version of the AVG standard.
viewportHeight Positive number <height> The height of the viewport
viewportWidth Positive number <width> The width of the viewport
width Positive absolute Dimension REQUIRED The width of the graphic.

This example defines a simple diamond filled with red:

{
  "type": "AVG",
  "version": "1.2",
  "height": 100,
  "width": 100,
  "items": {
    "type": "path",
    "fill": "red",
    "stroke": "blue",
    "strokeWidth": 4,
    "pathData": "M 50 0 L 100 50 L 50 100 L 0 50 z"
  }
}

data

An array of arbitrary data. When a data array is provided, the graphic inflates one item out of the items array for each element in the data array. The data, index, and length properties are added to the data-binding context.

height

The default absolute height of the AVG object. This is the height on the screen that the AVG object will take unless overridden or scaled in some fashion. It must be an absolute dimension.

item, items

An array of AVG items. The array is in the drawing order. Later items appear on top of earlier items. An AVG item has a type property:

Each item with a true when property inflates. The index and length properties are added to the data-binding context for each item. This is the "simple array of child items" inflation algorithm.

The inflation algorithm changes when the data property contains a value. For each item in the data array, the first child item in the items array with a true when property inflates. The data, index, and length properties are added to the data-binding context. This is the "data array" inflation algorithm.

resources

See AVG resources

parameters

An array of named values to add to the data-binding context when evaluating the AVG data. Each parameter is an object containing the following:

Property Type Required Description
name String Yes The name of the parameter
description String No An optional description of the parameter
type any | string | number | color No The type of the parameter. Defaults to "any"
default any No The default value to assign to the parameter. Defaults to the empty string (if type is not specified) or a type-appropriate empty value

The following APL document defines a circle vector graphic with parameters for the color and stroke width. The Container in the document inflates the graphic three times with different parameter settings:

{
  "type": "APL",
  "version": "1.5",
  "graphics": {
    "parameterizedCircle": {
      "type": "AVG",
      "version": "1.2",
      "height": 100,
      "width": 100,
      "parameters": [
        {
          "name": "circleColor",
          "type": "color",
          "default": "black"
        },
        {
          "name": "circleBorderWidth",
          "type": "number",
          "default": 2
        }
      ],
      "items": [
        {
          "type": "path",
          "pathData": "M25,50 a25,25 0 1 1 50,0 a25,25 0 1 1 -50,0",
          "stroke": "${circleColor}",
          "strokeWidth": "${circleBorderWidth}",
          "fill": "none"
        }
      ]
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Container",
      "direction": "row",
      "items": {
        "type": "VectorGraphic",
        "source": "parameterizedCircle",
        "width": 100,
        "height": 100,
        "circleColor": "${data.color}",
        "circleBorderWidth": "${data.width}"
      },
      "data": [
        {
          "color": "red",
          "width": 5
        },
        {
          "color": "green",
          "width": 10
        },
        {
          "color": "blue",
          "width": 15
        }
      ]
    }
  }
}

For convenience, if a named parameter only has a name, it can be abbreviated to a simple string.

In addition to user-defined parameters there are two implicitly supplied parameters: height and width (both numbers). These are scaled viewportWidth and viewportHeight values. For example, assume that the vector graphic of height startingPixelHeight has been placed in a container and told to scale to a new size scaledPixelHeight. The internally bound height and width values are given by:

function calculateScale( double scale, ScaleType scaleType ) {
  switch (scaleType) {
    case "none":
      return 1.0;
    case "grow":
      return scale > 1.0 ? scale : 1.0;
    case "shrink":
      return scale < 1.0 ? scale : 1.0;
    case "stretch":
      return scale;
  }
}

height = viewportHeight * calculateScale( scaledPixelHeight / startingPixelHeight, scaleTypeHeight );
width = viewportWidth * calculateScale( scaledPixelWidth / startingPixelWidth, scaleTypeWidth );

scaleTypeHeight & scaleTypeWidth

The scaleTypeHeight and scaleTypeWidth properties control how the internal (viewport) height and width of the graphic resize when scaled. Valid options are:

ScaleType Description
none The viewport dimension does not change (the default)
stretch The viewport dimension grows or shrinks proportionally to the change in drawing dimension.
grow The viewport dimension may grow proportionally, but does not shrink.
shrink The viewport dimension may shrink proportionally, but does not grow.

Consider a "pill-shaped" vector graphic, such as for a vertical scrollbar or indicator. The design of the graphic is a tall hollow rectangle with rounded corners at the top and bottom. When the vector graphic is stretched vertically the intent is to keep the shape of the rounded corners the same and stretch the center vertical lines. An easy way to define this graphic is to allow the viewport to stretch vertically and insert into the drawing path a parameterized expression that draws the vertical segment of the path based on the viewport height. For example:

    {
      "type": "APL",
      "version": "1.5",
      "graphics": {
        "myPillShape": {
          "type": "AVG",
          "version": "1.2",
          "height": 100,
          "width": 100,
          "parameters": [ "myScaleType" ],
          "scaleTypeHeight": "${myScaleType}",
          "items": [
            {
              "type": "path",
              "pathData": "M25,50 a25,25 0 1 1 50,0 l0 ${height-100} a25,25 0 1 1 -50,0 z",
              "stroke": "black",
              "strokeWidth": 20
            }
          ]
        }
      },
      "mainTemplate": {
        "parameters": [
          "payload"
        ],
        "item": {
          "type": "Container",
          "direction": "row",
          "items": {
            "type": "VectorGraphic",
            "source": "myPillShape",
            "width": 100,
            "height": 200,
            "scale": "fill",
            "myScaleType": "${data}"
          },
          "data": [
            "none",
            "stretch"
          ]
        }
      }
    }
Non-uniform scaling on the left and the 'stretch' behavior on the right
Non-uniform scaling on the left and the 'stretch' behavior on the right

In this example, the left image shows what happens when the viewport is not allowed to stretch and the right image shows what happens when the viewport is scaled up. In the left image, the viewport is drawn in a 100 by 100 unit viewport and then stretched to fill a 100 by 200 dp rectangle on the screen. The resulting image is a distorted circle. On the right, the viewport scaling is set to stretch, so the graphic is drawn in a 100 by 200 unit viewport. The height property is bound in the context to the scaled viewport height, so the pathData is now drawn with an extra vertical line segment of length ${height - 100} or 100 units.

styles

See AVG styles.

type

A string set to AVG.

version

A string set to the version of the AVG standard used by this vector graphic.

The most recent version of AVG is 1.2.

AVG 1.2 is supported in APL 1.5 and later.

viewportHeight

The height of the drawing coordinates used internally in the AVG object. If not specified, this defaults to height.

viewportWidth

The width of the drawing coordinates used internally in the AVG object. If not specified, this defaults to width.

width

The default width dimension of the AVG object. This is the amount of space on the screen that the AVG object will take unless overridden or scaled in some fashion. It must be an absolute dimension.

AVG resources

AVG graphic resources are named entities that are accessible through data-binding and value resolution. AVG resources follow the same structure as APL resources. AVG resources are evaluated when the graphic is loaded. The data-binding context used is the global document data-binding context with the document-level resources loaded. Resources are static and may not be changed. Graphic resources may refer to document-level resources with the @name syntax.

A sample graphic resource block:

"resources": [
  {
    "color": {
      "accent": "#00CAFF",
      "myBlue": "#66DFFF",
    },
    "number": {
      "lineWidth": 2
    },
    "string": {
      "checkmark": "M0,20 l10,10 l40,-40"
    },
    "pattern": {
      "redCircle": {
        "width": "18",
        "height": "18",
        "item": {
          "type": "path",
          "pathData": "M0,9 a9,9 0 1 1 18,0 a9,9 0 1 1 -18,0",
          "fill: "red"
        }
      }
    }
  },
  {
    "when": "${viewport.width > 1000}",
    "number": {
      "lineWidth": 4
    }
  },
  {
    "when": "${viewport.theme == 'light'}",
    "color": {
      "accent": "#0070BA",
      "myBlue": "@documentDarkBlue"
    }
  }
]

Resources are defined in blocks, where a block is an object with an optional when clause and a set of types. The properties of each resource block are:

Property Type Required Description
boolean, booleans Map of Boolean No A mapping from boolean name to boolean value
color, colors Map of Colors No A mapping from color name to color value
description String No A description of this resource block
easing, easings Map of Easings No A mapping from easing name to easing definition
gradient, gradients Map of Gradients No A mapping from gradient name to gradient definition
number, numbers Map of Numbers No A mapping from a name to a number.
pattern, patterns Map of Patterns No A mapping from name to a pattern
string, strings Map of Strings No A mapping from a name to a string.
when Boolean No If true, this resource block will be included. Defaults to true.

The resource blocks are processed in array order, with later definitions overriding earlier definitions.

A resource definition may refer to a resource defined in an earlier block using the @name syntax.

boolean

Boolean resources are stored as true/false values. Any non-Boolean assigned to a boolean resource will be converted using the "truthy" rules. For details about these rules, see Truthy and Coercion. For example:

"boolean": {
  "a": true,   // True
  "b": null,   // False
  "c": ""      // False
  "d": 22      // True
}

color

Color values are stored as colors, which are 32-bit RGBA values. For details about how write string expressions that convert to colors, see Data Types. For general coercion rules, see Color coercion.

"colors": {
  "myRed1": "#ff0000ff",    // Normal Red
  "myRed2": "#ff0000",      // Short version (drops the alpha),
  "myRed3": "#f00",         // Super-short version (each R,G,B is doubled)
  "myRed4": "red",          // Take advantage of built-in color names
  "myRed5": "rgb(255,0,0)", // RGB function
  "myRed6": 4278190335      // Not recommended: hex value of 0xff0000ff
}

easing

Easing functions are single-valued functions traditionally used to define how how an animated property changes over time. For details about easing functions, see Easing functions.

gradient

Gradients are defined following the rules in the AVG gradients section. For example:

"gradient": {
  "redWhite": {
    "type": "linear",
    "colorRange": [ "@myRed1", "white"],
    "inputRange": [ 0, 1 ],
    "angle": 90
  }
}

number

Number resources are stored as double precision floating point values internally. For details about how non-numeric values convert to numbers, see Number coercion.

"numbers": {
  "a": 23,
  "b": "${viewport.width / viewport.height}"
}

pattern

Pattern resources are AVG graphic objects that are used to fill or stroke paths. For example:

"pattern": {
  "CirclePattern": {
    "description": "Repeating pattern of circles",
    "viewportWidth": 20,
    "viewportHeight": 20,
    "width": "25%",
    "height": "25%"
    "items": {
      "type": "path",
      "fill": "red",
      "pathData": "M0,10 a10,10 0 1 1 20,0 a10,10 0 1 1 -20,0"
    }
  }
}

For details, see AVG patterns.

string

String values are stored as strings. Other types are converted to strings. For the string conversion rules, see String coercion.

"strings": {
   "a": null,          // ""
   "b": "",            // ""
   "c": false,         // "false"
   "d": 23,            // "23"
   "e": "${@myRed1}"   // "#ff0000ff" (by the color definition above)
}

when

If when is true (or not specified), this resource block will be processed and added to the defined AVG resources. If when is false, the resource block is skipped.

AVG gradients

A gradient is a shaded color pattern for fills and strokes. AVG supports linear and radial gradients. An AVG gradient specified in a resource is constant and will not change at run time. An AVG gradient specified directly in a fill or stroke property can be dynamic (with internal data-bound properties).

An example of an AVG graphic containing linear and radial gradients is:

{
  "type": "AVG",
  "version": "1.2",
  "width": 358,
  "height": 150,
  "resources": {
    "gradients": {
      "linearGradient": {
        "inputRange": [
          0,
          0.5492504222972973,
          1
        ],
        "colorRange": [
          "#ffffffff",
          "#ff0000ff",
          "#000000ff"
        ],
        "type": "linear",
        "x1": 0.30127709565476446,
        "y1": 0.4259174391256225,
        "x2": 0.7981258206624885,
        "y2": 0.5839892388973439
      },
      "radialGradient": {
        "inputRange": [
          0,
          1
        ],
        "colorRange": [
          "#ffffffff",
          "#ff0000ff"
        ],
        "type": "radial",
        "centerX": 0.6480013075429227,
        "centerY": 0.4348329629565578,
        "radius": 1
      }
    }
  },
  "items": [
    {
      "type": "path",
      "description": "Linear Star",
      "fill": "@linearGradient",
      "stroke": "#979797ff",
      "strokeWidth": 1,
      "pathData": "M86.5,120 L38.5955019,144.103326 L47.744447,93.0516628 L8.98889392,56.8966744 L62.547751,49.4483372 L86.5,3 L110.452249,49.4483372 L164.011106,56.8966744 L125.255553,93.0516628 L134.404498,144.103326 L86.5,120 Z"
    },
    {
      "type": "path",
      "description": "Radial Star",
      "fill": "@radialGradient",
      "fillTransform": "translate(0.648001,0.434833) matrix(-0.348987 0.320740 -0.306966 -0.364646 0 0) translate(-0.648001,-0.434833)",
      "stroke": "#979797ff",
      "strokeWidth": 1,
      "pathData": "M261.5,120 L213.595502,144.103326 L222.744447,93.0516628 L183.988894,56.8966744 L237.547751,49.4483372 L261.5,3 L285.452249,49.4483372 L339.011106,56.8966744 L300.255553,93.0516628 L309.404498,144.103326 L261.5,120 Z"
    }
  ]
}

AVG gradients are a subset of the SVG gradient standard and don't match the gradient definition used for components. The component gradients may be used in AVG documents, but it is recommended that you use only the AVG gradients because component gradients will not scale in the same way and have fewer features.

Common

All AVG gradients share the following properties:

Property Type Default Description  
type linear radial REQUIRED Defines the gradient type
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.  
units userSpace boundingBox boundingBox The coordinate system for positioning

There are two types of AVG gradient:

type

The type of the gradient must be defined and must be either "linear" or "radial".

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.

If specified, the inputRange must (a) have the same number of elements as the colorRange and (b) be in ascending numeric order with values in the range [0,1]. If the first value is greater than 0, the color range between zero and the first value is fixed to the first color. If the last value is less than 1, the color range between the last value and one is fixed to the last color.

units

Defines the coordinate system for positioning the gradient. The userSpace coordinate system interprets the positioning dimensions of the gradient in terms of the coordinate system in place for drawing the object. This is equivalent to the userSpaceOnUse setting in SVG. The boundingBox coordinate system interprets the position dimensions of the gradient mapping the values of (0,0) to the top-left of the bounding box of the path and (1,1) to the bottom-right of the bounding box of the path. The boundingBox value is equivalent to the objectBoundingBox setting in SVG.

Linear

A linear gradient contains the following properties in addition to the common properties:

Property Type Default Description    
spreadMethod pad / reflect / repeat / pad Gradient behavior outside of the defined range
x1 Number 0% The x-position of the start of the gradient    
x2 Number 100% The x-position of the end of the gradient    
y1 Number 0% The y-position of the start of the gradient    
y2 Number 100% The y-position of the end of the gradient    

For a linear gradient the spreadMethod is set to "pad" and the x1, x2, y1, and y2 values are calculated so that the angle is correct as defined in the unit square such that the first and last color are set on the opposite corners of the bounding rectangle of the object.

spreadMethod

The linear gradient spread method defines how the gradient will repeat outside of the bounds of the box defined by (x1,y1) to (x2,y2).

x1/y1/x2/y2

These points define the starting and endpoint point of the gradient box. The first color in the color range will be drawn at (x1,y1). The last color in the color range will be drawn at (x2,y2). Colors are interpolated between those two points following the rules for the color and input range.

The coordinate system used for the gradient is defined by the units property. When the units property is boundingBox, these values are percentages of the bounding rectangle surrounding the object being stroked or filled. It is important to note that the same gradient used in shapes with different aspect ratios will result in a different apparent visual angle. The fillTransform and strokeTransform can be used to correct the visual angle.

Radial

A radial gradient contains the following properties in addition to the common properties:

Property Type Default Description
centerX Number 50% The x-position of the center of the gradient
centerY Number 50% The y-position of the center of the gradient
radius Positive number 70.71% The radius of the gradient (distance to end)

For a radial gradient the centerX and centerY values are fixed to 50% and the radius value is fixed to 70.71%. This ensures that the first color is in the center of the object and the last color is set on the corners of the bounding rectangle of the object.

centerX/centerY

This point defines the center of the radial gradient. The point is defined in the percentage of the bounding rectangle surrounding the object being filled or stroked when the units property is set to boundingBox and is in local coordinates when userSpace.

radius

The radius of the gradient is defined as the percentage of the width/height of the bounding rectangle surrounding the object being filled or stroked. Please note that a radial gradient drawn in a non-square object using boundingBox units will appear as an ellipse unless you applied a gradient transformation to compensate for the aspect ratio of the object. The fillTransform and strokeTransform can be used to correct the visual angle.

AVG filters

AVG filters apply effects to the graphic produced by AVG items before displaying the item.

The following example creates a red diamond graphic. The DropShadow filter adds a drop-shadow to the graphic.

Copied to clipboard.

{
  "type": "AVG",
  "version": "1.2",
  "width": "120px",
  "height": "120px",
  "items": {
    "type": "path",
    "fill": "red",
    "stroke": "blue",
    "strokeWidth": 4,
    "pathData": "M 60 10 L 110 60 L 60 110 L 10 60 z",
    "filters": [
      {
        "type": "DropShadow",
        "color": "black",
        "horizontalOffset": -3,
        "radius": 3,
        "verticalOffset": 3
      }
    ]
  }
}
A red diamond with blue border graphic which has a DropShadow filter with radius=3, verticalOffset=3, and horizontalOffset=-3
A red diamond with blue border graphic which has a DropShadow filter with radius=3, verticalOffset=3, and horizontalOffset=-3

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

The first filter in the array receives as input the graphic drawn from the parent AVG item or items. Each subsequent filter in the array receives the output of the previous filter as the input. The output of the final filter in the array is displayed.

You can use the filters listed in the following table.

Type Description
DropShadow Adds a drop shadow to the source image

DropShadow

The DropShadow filter copies the input graphic and replaces the RGB values with the specified shadow color. The alpha channels of the source graphic and the shadow color are multiplied together to determine the shadow alpha. The shadow graphic is then blurred, translated by the specified offsets, and copied behind the original input graphic. The offset and blur radius values are interpreted in terms of the AVG coordinate system.

Property Type Default Description
type DropShadow REQUIRED Set to DropShadow
color Color Black Color of the shadow
horizontalOffset Number 0 Horizontal offset of the shadow
radius Non-negative Number 0 Blur radius of the shadow
verticalOffset Number 0 Vertical offset of the shadow

The shadow produced is bound by dimensions of the AVG object. The DropShadow filter draws the shadow behind all AVG items and the filter results of any AVG items which are earlier in the drawing order.

The left side show the text item source graphic and the right side shows the result of applying a DropShadow filter to it with the default color black, vertical and horizontal offsets of 5, and a blur radius of 5.
The left side show the text item source graphic and the right side shows the result of applying a DropShadow filter to it with the default color black, vertical and horizontal offsets of 5, and a blur radius of 5.

AVG patterns

AVG patterns are non-parameterized re-usable vector graphic elements that can be applied to path stroke and fill properties. An AVG pattern is an object with the following properties:

Property Type Default Description
description String "" Optional description of this pattern.
height Positive number REQUIRED Height of the pattern
item, `items Array of AVG items [] An array of drawing items
width Positive number REQUIRED Width of the pattern

AVG patterns must be defined in an AVG pattern resource. The drawing operations inside of the AVG pattern are applied in drawing box from 0,0 to width,height. Drawing operations outside of this bounding box are clipped.

Internally AVG patterns may be rendered once to an offscreen bitmap and then used as a bitmap shader when drawing a path or text element. If the pattern is upscaled during rendering, pixelation artifacts may be visible. It is recommended that patterns be kept as small as practical and not upscaled.

height

The height of the pattern in the coordinates appropriate for the path it is being drawn within. Both width and height must be positive numbers or the pattern will not draw.

item, items

An array of AVG items. The array is in the drawing order where later items appear on top of earlier items. All drawing items are supported including:

width

The width of the pattern in the coordinates appropriate for the path it is being drawn within. Both width and height must be positive numbers or the pattern will not draw.

AVG styles

AVG styles are APL styles that apply only within a single vector graphic. All AVG properties can be styled. For details about APL styles, see APL Style Definition and Evaluation.

An AVG style definition specifies the name of the style, a list of one or more parent styles to inherit from, and an ordered list of conditionally-applied property definitions:

"styles": {
  "BasicButton: {
    "values": [
      {
        "strokeWidth": 5,
        "stroke": "red",
        "fill": "@StandardFillResource"
      },
      {
        "when": "${state.focused}",
        "stroke": "green",
      },
      {
        "when": "${state.pressed}",
        "stroke": "blue"
      }
    ]
  },
  "FancyButton": {
    "extends": "BasicButton",
    "values": [
      {
        "when": "${state.pressed}",
        "stroke": "@FancyButtonGradient"
      }
    ]
  }
}

Each style definition has the following properties:

Property Type Default Description
description String "" A description of this style
extend, extends Array of style names [] List the styles that this style inherits from. Order is important; later styles override earlier.
value, values Array of VALUE objects [] An array of objects

extend, extends

The extends array contains an ordered list of names of styles that this style inherits from. These styles may be a locally-defined AVG style or a global APL style. If two styles referenced in the extends array define the same property, the style later in the list overrides the property definition.

values, values

The values array contains an ordered list of value objects to apply. Each value object has the form:

{
  "when": EXPRESSION,
  NAME: VALUE,
  NAME: VALUE,
  :
}

The when property is optional and defaults to true if it is not defined. The defined properties are expected to be the names of valid styled properties (they are ignored if they are invalid names). The data-binding context for the when clause contains the viewport, environment, resource definitions, and styles that appear earlier in the graphic, document or in imported packages.

AVG base item

An AVG base item is an abstract class specifying common AVG item properties. There are three concrete types of AVG items:

All AVG items support the properties shown in the following table.

Property Type Default Description
bind Array of Binding [] Expressions to add to the data
description String "" Optional description of the AVG item
filter, filters Array of AVG filters [] Filters to apply to this item.
style String "" Named style to apply
type path | group | text REQUIRED Type of AVG item
when Boolean true When true, inflate this item. Whenfalse, don't inflate this item.

bind

The bind property of an AVG item extends the data-binding context for the item and its children. The bind property specifies an ordered set of data-bindings that extend the current context. Bindings are ordered; later bindings can use previous definitions. Each binding object in the binding array contains the properties shown in the following table.

Property Type Default Description
name String REQUIRED The name to use for this binding. Must be a valid name.
value Any REQUIRED The value to assign to this binding.
type any, boolean, string, number, color, array, or map any Property type.

The bind property evaluates after the when property and before any other properties. Bindings are added to the data-binding context in array order; later bindings may use the results from earlier bindings.

The following example shows two bindings (ReallyWide and Tallish) that use the first binding (AspectRatio).

Copied to clipboard.

{
  "type": "text",
  "bind": [
    {"name":"AspectRatio","value":"${width/height}"},
    {"name":"ReallyWide","value":"${AspectRatio > 2}"},
    {"name":"Tallish","value":"${AspectRatio < 1}"}
  ],
  "text": "This box is ${ReallyWide ? 'too wide' : 'just right'}",
  "fill": "${Tallish ? 'blue' : 'green'}"
}

To avoid conflict with internal APL-defined data-bound properties, capitalize the names of bound properties. For example, use "AspectRatio" instead of "aspectRatio".

When a binding has a type property, the calculated result of the binding is assigned to be that type (except for "any").

In the following example, the TALL property is assigned the string value of "true" or "false" depending on the current width and height.

Copied to clipboard.

{
  "bind": {
    "name": "TALL",
    "type": "string",
    "value": "${width < height}"
  }
}

filter, filters

One or more filtering operations to apply to the drawing of all items in this group before they are displayed. The group filters are applied after all items in the group are drawn and had their filters applied. For details about filters, see AVG Filters

style

The named AVG style to apply to this item. For details, see AVG styles.

type

Specifies the particular item type to inflate. It can be one of the following:

The type property is required.

when

If true, inflate the AVG item. If false, ignore the AVG item and all of its child items.

AVG path item

An AVG path item defines one or more rendered shapes with common fill and strokes. An AVG path item has the following properties:

The AVG path item has the following properties:

Property Type Default Description
type "path" REQUIRED Must be set to "path".
fill Color transparent The fill color.
fillOpacity Number 1 The opacity of the path fill.
fillTransform Transform "" Transformation applied against the fill gradient or pattern
pathData String REQUIRED The path drawing data.
pathLength Non-negative number 0 If defined, specifies the "length" of the path
stroke Color transparent The color used to draw the stroke.
strokeDashArray Array of length [] Pattern of dashes and gaps
strokeDashOffset length 0 Offset into dash array pattern
strokeLineCap butt, round, square butt Shape to be used at the end of open paths
strokeLineJoin bevel, miter, round miter How path corners are drawn
strokeMiterLimit Positive number 4 When sharp path corners are beveled
strokeOpacity Number 1 The opacity of the path stroke.
strokeTransform Transform "" Transform applied against the stroke gradient or pattern
strokeWidth Number 1 The width of the path stroke.

At a minimum, specify either the fill or stroke. If neither fill or stroke are provided, the graphic is not drawn.

fill

The color, gradient, or pattern used to fill the path. If not specified, the fill will not be drawn.

The following example creates a square filled with a gradient.

{
  "gradientSquare": {
    "type": "AVG",
    "version": "1.2",
    "height": 100,
    "width": 100,
    "resources": [
      {
        "gradients": {
          "RedWhite": {
            "type": "linear",
            "colorRange": ["red","white"],
            "inputRange": [0,1],
            "angle": 90
          }
        }
      }
    ],
    "items": {
      "type": "path",
      "pathData": "M0,0 L40,0 L40,40 L0,40",
      "fill": "@RedWhite"
    }
  }
}

This example creates a square filled with a repeating pattern.

{
  "patternSquare": {
    "type": "AVG",
    "version": "1.2",
    "height": 100,
    "width": 100,
    "resources": [
      {
        "patterns": {
          "RedCircle": {
            "width": 8,
            "height": 8,
            "items": [
              {
                "type": "path",
                "fill": "red",
                "pathData": "M0,4 a4,4,0,1,1,8,0 a4,4,0,1,1,-8,0"
              }
            ]
          }
        }
      }
    ],
    "items": {
      "type": "path",
      "pathData": "M0,0 L40,0 L40,40 L0,40",
      "fill": "@RedCircle"
    }
  }
}

With resources and parameters, you can combine these definitions into a single AVG definition, then pass in the fill type.

Example of color, gradient, and pattern fills
Example of color, gradient, and pattern fills

fillOpacity

The applied opacity of the fill. The fill color can also include an opacity, in which case the final fill opacity will be the product of the fillOpacity and the nested opacity properties of surrounding groups and the hosting component.

fillTransform

A matrix transformation to be applied against the fill gradient or pattern. The fillTransform has no effect on simple colored fills. For the transform syntax, see the transform property in the AVG group item section.

pathData

A string containing one or more path commands, as defined by the SVG "d" specification. The following table summarizes the path commands.

Command Parameters Description

M, m

(x,y)+

Move to the beginning of the next sub-path in absolute coordinates. Additional pairs are implicit "L" commands. The "m" variant uses relative coordinates

L, l

(x,y)+

Draw a line from the current location to the new location in absolute coordinates. Pairs may be repeated for additional lines. The "l" variant uses relative coordinates

H, h x+ Draw a horizontal line in absolute (H) or relative (h) coordinates
V, v y+ Draw a vertical line in absolute (V) or relative (v) coordinates

C, c

(x1,y1,x2,y2,x,y)+

Draw a Bézier curve from the current point to x,y, using x1,y1,x2,y2 as control points. Uses absolute (C) or relative (c)

S, s

(x2,y2,x,y)+

Draw a smooth Bézier curve from the current point to x,y using x2,y2 as the control point at the end of the curve. Uses absolute (S) or relative (s) coordinates

Q, q

(x1,y1,x,y)+

Draw a quadratic Bézier curve to the coordinates x,y with x1,y1 as the control point. Absolute (Q) or relative (q) coordinates.

T, t

(x,y)+

Draw a smooth quadratic Bézier curve to the coordinate x,y, where the control point carries over from the previous curve. Absolute (T) or relative (t) coordinates

A, a

Z, z

(rx ry angle large-arc-flag sweep-flag x y)+

Draw an elliptical arc curve to the coordinates x,y. The radii of the ellipse are rx, ry. The rotation of the ellipse is angle. The flags choose which segment of the arc to draw and which direction. Absolute (A) or relative (a) coordinates. Close the current subpath with a straight line between the start point and end point. Note that fill will not be affect by closing a subpath, but stroke will.

Refer to the SVG specification for the authoritative definition.

pathLength

The pathLength lets authors specify a total length of the path in user-defined units. This value is then used to adjust distance calculations by scaling the strokeDashArray and strokeDashOffset properties using the ratio pathLength/(true path length).

A user-specified negative or zero pathLength is ignored.

stroke

The color, gradient, or pattern used to stroke the path. If not specified, the stroke will not be drawn.

The following example creates a square with a gradient stroke.

"resources": {
  "gradients": {
    "RedWhite": {
      "type": "linear",
      "colorRange": [ "red", "white" ],
      "inputRange": [0, 1],
      "angle": 90
    }
  }
}
...
{
  "type": "path",
  "pathData": "M4,4 l32,0 l0,32 l-32,0",
  "strokeWidth": 4,
  "stroke": "@RedWhite"
}

The following example creates a square with a pattern stroke.

"resources": {
  "patterns": {
    "RedCircle": {
      "width": 8,
      "height": 8,
      "pathData": "M0,4 a4,4,0,1,1,8,0 a4,4,0,1,1,-8,0",
      "fill": "red"
    }
  }
}
...
{
  "type": "path",
  "pathData": "M4,4 l32,0 l0,32 l-32,0",
  "strokeWidth": 4,
  "fill": "@RedCircle"
}

strokeDashArray

The strokeDashArray is an array of numbers that defines the pattern of dashes and gaps used to stroke the path. If the array is empty, the stroke is solid. If the array contains an odd number of elements, it is implicitly doubled. For example, the array [1] is interpreted as [1 1] and [1,2,3] is interpreted as [1,2,3,1,2,3]. The odd indices in the array are the dash lengths (in viewport drawing units); the even indices in the array are the space lengths (in viewport drawing units). Non-positive numbers will generate undefined behavior.

The pathLength affects the strokeDashArray: each dash and gap length is interpreted relative to the pathLength.

The individual elements in the strokeDashArray must be non-negative numbers. The sum of the elements in the strokeDashArray must be a positive number. The visible appearance of dashes with length zero depends on the the strokeLineCap where a "butt" element will not be drawn, a "round" element will appear as a circle with diameter equal to the strokeWidth and the "square" element will appear as a square with side length equal to the strokeWidth.

strokeDashOffset

The strokeDashOffset shifts the starting point of the strokeDashArray by the specified number of viewport drawing units. For example, if the strokeDashArray is [2 1], then a strokeDashOffset of 2 would cause the line to begin drawing with a space.

The pathLength affects the strokeDashOffset: each dash and gap length is interpreted relative to the pathLength.

strokeLineCap

The strokeLineCap property determines the shape to be used at the ends of open paths.

strokeLineJoin

The strokeLineJoin property determines how sharp corners in a path will be drawn.

strokeMiterLimit

The strokeMiterLimit property determines when miter joints in paths should be turned into bevel joints.

strokeOpacity

The applied opacity of the stroke. The stroke color can also include an opacity, in which case the final stroke opacity is the product of the strokeOpacity and the overall opacity.

strokeTransform

A matrix transformation to be applied against the stroke gradient or pattern. The strokeTransform has no effect on simple colored strokes. Refer to transform for the transform syntax.

strokeWidth

The width of the stroke. Defaults to 1. The stroke is centered relative to the position of the path.

AVG group item

An AVG group applies transformations to its child items. An AVG group item has the following properties:

Property Type Default Description
type "group" REQUIRED Must be set to "group".
clipPath String None Clipping path.
data Array <none> Data to bind into the child items.
item, items Array of AVG items [] Array of child drawing items.
opacity Number 1.0 The opacity of the group.
transform Transform "" Transform applied to the contents of the group.

clipPath

The clipping path is a pathData line that is not drawn. Instead, it clips the children of the group. The clipping is done within the group coordinate system.

data

An array of arbitrary data. When a data array is provided the AVG graphic inflates one item out of the items array for each element in the data array. The data, index, and length properties are added to the data-binding context.

item, items

An array of AVG items. The array is in the drawing order; later items appear on top of earlier items. An AVG item has a type property. There are three types:

Each item with a true when property inflates. The index and length properties are added to the data-binding context for each item. This is the "simple array of child items" inflation algorithm.

The inflation algorithm changes when the data property contains a value. For each item in the data array, the first child item in the items array with a true when property inflates. The data, index, and length properties are added to the data-binding context. This is the "data array" inflation algorithm.

opacity

An overall opacity to apply to this group. The opacity is multiplicative with other opacities.

transform

Transform applied to the contents of the group. The transform property is a text string following the SVG syntax.

transform     ::= ( `rotate` | `scale` | `translate` | `skewX` | `skewY` )*
rotate        ::="rotate" "(" `angle` [ `x` `y` ] ")"
scale         ::="scale" "(" `sx` [ `sy` ] ")"
translate     ::="translate" "(" `x` [ `y` ] ")"
skewX         ::="skewX" "(" `angle` ")"
skewY         ::="skewY" "(" `angle` ")"

Non-numeric characters (including spaces and commas) are ignored. Angles are in degrees. A positive rotation value is a clockwise rotation about the origin of the group. The coordinate system has positive x values to the right and positive y values down. The origin is normally in the top-left.

The following are equivalent:

translate(x)  ⟺ translate(x 0)
scale(s)      ⟺ scale(s s)
rotate(a x y) ⟺ translate(x y) rotate(a) translate(-x -y)

Vector graphics may use data-bound expressions in the transform property. For example, to make the minute hand of an analog clock rotate correctly:

"transform": "rotate(${Time.minutes(localTime)*6})"

Alternative transform properties

In certain circumstances it is easier to write transformation properties as separate stages of scale, rotate, and translate. The alternative transform properties provide an explicit series of properties. These properties are only available if the transform property is not specified. If that property is specified, these properties are ignored.

Property Type Default Description
rotation Number 0 Rotation angle of the group, in degrees.
pivotX Number 0 X-coordinate of the rotation pivot point (viewport coordinates)
pivotY Number 0 Y-coordinate of the rotation pivot point (viewport coordinates)
scaleX Number 1.0 Scaling factor on the X-axis.
scaleY Number 1.0 Scaling factor on the Y-axis.
translateX Number 0 X-coordinate translation (viewport coordinates)
translateY Number 0 Y-coordinate translation (viewport coordinates)

The transformations are applied in the order of scale, rotate, and then translate. The equivalent transformation can be defined by the transform property, where:

"transform": "translate(tx ty) rotate(rotation px py) scale(sx sy)"

AVG text item

An AVG text item displays a single line of text. An AVG text item has the following properties:

Property Type Default Description
type "text" REQUIRED Indicates this item is a text item.
fill Color, Gradient, or Pattern black The text fill color, gradient, or pattern
fillOpacity Number 1 The opacity of the text fill.
fillTransform Transform "" Transformation applied against the fill gradient or pattern
fontFamily String sans-serif The name of the font family
fontSize Positive number 40 The size of the font
fontStyle normal, italic normal The style of the font
fontWeight normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900 normal The weight of the font
letterSpacing Number 0 Additional space to add between letters
stroke Color, Gradient, or Pattern transparent The text stroke color, gradient, or pattern.
strokeOpacity Number 1 The opacity of the text stroke.
strokeTransform Transform "" Transform applied against the stroke gradient or pattern
strokeWidth Non-negative number 0 The width of the text stroke.
text String "" The text to display
textAnchor start, middle, end start Direction the text hangs from the starting point
x Number 0 X-coordinate starting point (viewport coordinates)
y Number 0 Y-coordinate starting point (viewport coordinates)

If a text item draws with both stroke and fill, the fill is drawn first and the stroke overlays the fill.

The AVG text item shares a number of properties with the AVG path item and the Text component.

An example of a text item:

{
  "type": "AVG",
  "version": "1.2",
  "height": 60,
  "width": 150,
  "items": [
    {
      "type": "path",
      "pathData": "M0,0 l150,0 l0,60 l-150,0 Z",
      "fill": "#d8d8d8"
    },
    {
      "type": "text",
      "fill": "red",
      "fontFamily": "amazon-ember, sans-serif",
      "fontSize": 60,
      "text": "Hello",
      "x": 75,
      "y": 50,
      "textAnchor": "middle"
    }
  ]
}

fill

The fill property behaves the same as the path item's fill property.

fillOpacity

The fillOpacity property behaves the same as the path item's opacity property.

fillTransform

A matrix transformation to be applied against the fill gradient or pattern. The fillTransform has no effect on simple colored fills. Refer to transform for the transform syntax.

fontFamily

The fontFamily property behaves the same as the text component's fontFamily property.

fontSize

The size of the font, expressed in viewport units. Defaults to 40.

fontStyle

The fontStyle property behaves the same as the text component's fontStyle property.

fontWeight

The fontWeight property behaves the same as the text component's fontWeight property.

letterSpacing

Additional space to add between letters. The value may be negative. Defaults to 0. The letter spacing is specified in viewport units.

stroke

The stroke property behaves the same as the path item's stroke property.

strokeOpacity

The strokeOpacity property behaves the same as the path item's strokeOpacity property.

strokeTransform

A matrix transformation to be applied against the stroke gradient or pattern. The strokeTransform has no effect on simple colored strokes. Refer to transform for the transform syntax.

strokeWidth

The strokeWidth property behaves the same as the path item's strokeWidth property.

text

The text to display. The displayed text supports a subset of the formatting rules used in the Text component's text property. Inline markup strings (e.g., "<br>", "<em>") are ignored and will not be displayed. To display markup characters, they must be replaced with character entity references:

Entity Character Description
&amp; & Ampersand
&lt; < Less-than
&gt; > Greater-than
&\#nn; Any Decimal Unicode code-point. "nn" is a valid integer.
&\#xnn;   Hexadecimal Unicode code-point. "nn" is a valid hexadecimal number

Numeric entity references can be in decimal or hexadecimal. For example, © can be written &#169; or &#xa9;.

The string "Copyright &\#169; 2018, Simon \&amp; Schuster. \<br\>\<em\>All Rights Reserved\</em\>" is rendered on a single line.

Copyright © 2018, Simon & Shuster. All Rights Reserved

textAnchor

The direction the text hangs from the starting point (x,y). The following options are available:

Name Description
start The text starts at the starting point (x,y). For left-to-right languages, the text will extend to the right. For right-to-left languages, the text will extend to the left.
middle The text is centered about the starting point (x,y).
end The text ends at the starting point (x,y). For left-to-right languages, the text will extend to the left. For right-to-left languages, the text will extend to the right.

x

The x-coordinate of the baseline of the text. The textAnchor property controls whether the text extends to the left, right, or is centered at this point.

y

The y-coordinate of the baseline of the text. The textAnchor property controls whether the text extends to the left, right, or is centered at this point.

AVG inflation algorithm

Inflating an AVG object involves the following steps:

  1. Create a new data-binding context.
  2. Add to that data-binding context each of the parameters. Parameter values are calculated using the first match in the following order:
    1. Passed from the JSON inflation logic. For example, a user could pass in the fill externally. See VectorGraphic
    2. Extracted from the current style by name.
    3. The default value assigned to the parameter.
  3. Add to the data-binding context the calculated viewport width and height of the AVG object. Refer to scaleTypeHeight and scaleTypeWidth.
  4. Inflate the AVG JSON definition into nested groups, paths, and text objects, applying data-binding.