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.
lang String none The language specified for the vector graphic.
layoutDirection One of: LTR | RTL LTR The direction in which the graphic renders. Set this property for either left-to-right or right-to-left languages.
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.

The following example defines a graphic of a 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"
  }
}

To display the graphic, place a VectorGraphic component in your document. The following example adds the red diamond graphic to the graphics property of the document, then displays the VectorGraphic component centered in a Container.


data

An array of arbitrary data. When you provide a data array, 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 takes unless overridden or scaled. 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.

lang

Sets an AVG-wide language. When set, APL attempts to find a language-specific version of the fontFamily for all the AVG Text items inside the graphic. If no valid font is found, APL ignores this property and uses the specified fontFamily. When not set, APL uses the specified fontFamily.

Set the lang property to a BCP-47 string (for example, "en-US").

Note: Alexa devices might not have the font in specific language installed. Test the experience on the device or devices to confirm that it works.

layoutDirection

Sets an AVG-wide layout direction. When not set, defaults to LTR (left-to-right). The layoutDirection determines how the textAnchor property works for AVG Text items inside the graphic.

This property specifies the AVG-wide layoutDirection. Note: the AVG-wide layoutDirection isn't inherited from the document. If you don't specify layoutDirection, the default value is "LTR".

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 with the properties shown in the following table.

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 when type isn't 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.


For convenience, if a named parameter only has a name, you can abbreviate it to a string.

In addition to user-defined parameters there are two implicitly supplied number parameters: height and width. 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 and scaleTypeWidth

The scaleTypeHeight and scaleTypeWidth properties control how the internal (viewport) height and width of the graphic resize when scaled. The following table shows the valid options.

Scale Type Description

none

The viewport dimension doesn't change (the default).

stretch

The viewport dimension grows or shrinks proportionally to the change in drawing dimension.

grow

The viewport dimension can grow proportionally, but doesn't shrink.

shrink

The viewport dimension can shrink proportionally, but doesn't grow.

For example, consider a "pill-shaped" vector graphic, such as for a vertical scroll bar 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. One approach 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:


In this example, the left image shows the result when the viewport isn't 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 takes unless overridden or scaled. 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 can't be changed. Graphic resources can 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 easing functions

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 is included. Defaults to true.

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

A resource definition can 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 converts to a Boolean 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 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 is 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 doesn't change at run time. An AVG gradient specified directly in a fill or stroke property can be dynamic (with internal data-bound properties).

The following example shows an AVG graphic containing linear and radial gradients.

{
  "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"
    }
  ]
}

The following APL document gives this graphic the name gradientStars and displays the graphic centered in the viewport.


AVG gradients are a subset of the SVG gradient standard and don't match the gradient definition used for components. Although you can use component gradients in an AVG definition, this approach isn't recommended because component gradients might not scale in the same way and have fewer features. AVG gradients are recommended for AVG definitions.

Common

All AVG gradients share the properties shown in the following table.

Property Type Default Description

type

One of: linear or radial

Required

Defines the gradient type.

colorRange

Array of colors

Required

The color to assign at each gradient stop.

description

String

Optional description of this gradient.

inputRange

Array of numbers

The input stops of the gradient.

units

One of: userSpace or 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 isn't 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.

When 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

One of: pad, reflect, or 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 repeats 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 is drawn at (x1,y1). The last color in the color range is 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. Note that the same gradient used in shapes with different aspect ratios results 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. A radial gradient drawn in a non-square object using boundingBox units appears 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

An AVG filter applies effects to the graphic produced by AVG items before displaying the item.

The following document defines a graphic called redDiamondWithFilters that uses the DropShadow filter to add a drop-shadow to the graphic. This example uses a medium gray background to make the black shadow visible.


A filter has a type property that specifies the type of filter to apply. Filters are applied in the order they're 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 properties shown in the following table.

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 might be rendered one time to an offscreen bitmap and then used as a bitmap shader when drawing a path or text element. If the pattern is scaled up during rendering, pixelation artifacts might be visible. Keep patterns as small as practical and avoid scaling them up.

height

The height of the pattern in the coordinates appropriate for the path it's drawn within. Both width and height must be positive numbers or the pattern doesn't 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's drawn within. Both width and height must be positive numbers or the pattern doesn't 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 properties shown in the following table.

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 styles.

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 can be locally-defined AVG styles or global APL styles. 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 when not set. The defined properties are expected to be the names of valid styled properties. Invalid names are ignored.. 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

One of: path, group, or 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 extends the data-binding context for the item and its children with local bound variables. For details about bound variables, see APL Bound Variables.

filter, filters

One or more filtering operations to apply to the drawing of all items in this group before they're 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:

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

One of: butt, round, or square

butt

Shape to be used at the end of open paths

strokeLineJoin

One of: bevel, miter, or 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 isn't drawn.

fill

The color, gradient, or pattern used to fill the path. If not specified, the fill isn't 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.


fillOpacity

The applied opacity of the fill. The fill color can also include an opacity, in which case the final fill opacity is 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 can 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 sub-path with a straight line between the start point and end point. Note that fill isn't affected by closing a sub-path, but stroke is.

Refer to the SVG specification for the authoritative definition.

pathLength

The pathLength lets you 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 isn't 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's 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) and the even indices in the array are the space lengths (in viewport drawing units). Non-positive numbers 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 strokeLineCap where a "butt" element isn't drawn, a "round" element appears as a circle with diameter equal to the strokeWidth and the "square" element appears 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 causes 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 to draw sharp corners in a path.

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 isn't 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 opacity values.

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 can 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 might be 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 available when the transform property isn't specified. If transform contains a value, these alternative 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.

The following example shows text item graphic that displays red text over a light background.

{
  "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"
    }
  ]
}

The following APL document shows this text item centered in the viewport.


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 can 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 property of the Text component. Inline markup strings such as <br> and <em> are ignored and don't display. Replace markup characters with character entity references as shown in the following table.

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>" renders on a single line.

Copyright © 2018, Simon & Schuster. All Rights Reserved


textAnchor

The direction of the text relative to the starting point (x,y). The following table summarizes the options.

Name Description

start

The text starts at the starting point (x,y). When the layoutDirection property for the graphic is LTR, the text extends to the right. When the layoutDirection property is RTL, the text extends to the left.

middle

The text is centered about the starting point (x,y).

end

The text ends at the starting point (x,y). When layoutDirection is LTR, the text extends to the left. When layoutDirection is RTL, the text extends 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.

Was this page helpful?

Last updated: Feb 29, 2024