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.

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:

• Group
• Path
• Text

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.

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.

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:

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.

There are two types of AVG gradient:

• Linear
• Radial

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:

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:

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.

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.

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.

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.

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:

• AVG path item
• AVG group item
• AVG text item

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.

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:

• AVG path item
• AVG group item
• AVG text item

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

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:

• path – AVG path item
• group – AVG group item
• text – AVG text item

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:

• All AVG base item properties.
• The path item properties shown in the following table.

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.

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:

• All AVG base item properties.
• The group item properties shown in the following table.

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:

• Path
• Group
• Text

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.

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:

• All AVG base item properties.
• The text item properties shown in the following table.

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.

Numeric entity references can be in decimal or hexadecimal. For example, © can be written © or ©.

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.

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.

Related topics

• VectorGraphic component

Last updated: Feb 29, 2024