Alexa Vector Graphics Format

(This is not the most recent version of Alexa Graphics Format. Use the Other Versions option to see the documentation for the most recent version of Alexa 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.

Properties

An AVG object has the following properties:

This example defines a simple diamond filled with red:

{
  "type": "AVG",
  "version": "1.1",
  "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"
  }
}

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 draw on top of earlier items. An AVG item has a type property which determines the created AVG item. There are three types of items:

• Group
• Path
• Text

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:

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": "2024.3",
  "graphics": {
    "parameterizedCircle": {
      "type": "AVG",
      "version": "1.1",
      "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:

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": "2024.3",
      "graphics": {
        "myPillShape": {
          "type": "AVG",
          "version": "1.1",
          "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"
          ]
        }
      }
    }

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.

This document describes AVG version 1.1. This is not the most recent version of the AVG format. Use the Other Versions button at the top of the page to see documentation for other versions AVG.

AVG 1.1 was introduced with APL 1.4.

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:

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.1",
  "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:

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 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:

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:

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 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:

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:

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

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:

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 path item

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

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.1",
    "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.1",
    "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 document: AVG fill examples  

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "graphics": {
    "squareWithFills": {
      "type": "AVG",
      "version": "1.1",
      "parameters": [
        {
          "name": "myFillType",
          "default": "red"
        }
      ],
      "resources": [
        {
          "gradients": {
            "RedWhite": {
              "type": "linear",
              "colorRange": [
                "red",
                "white"
              ],
              "inputRange": [
                0,
                1
              ],
              "angle": 90
            }
          },
          "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"
                }
              ]
            }
          }
        }
      ],
      "height": 100,
      "width": 100,
      "items": {
        "type": "path",
        "pathData": "M0,0 L40,0 L40,40 L0,40",
        "fill": "${myFillType}"
      }
    }
  },
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100%",
        "height": "100%",
        "paddingTop": "16dp",
        "paddingLeft": "16dp",
        "paddingRight": "16dp",
        "paddingBottom": "16dp",
        "items": [
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "red"
          },
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "@RedWhite"
          },
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "@RedCircle"
          }
        ],
        "direction": "row",
        "alignItems": "center",
        "justifyContent": "center"
      }
    ]
  }
}

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.

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.

style

The named AVG style to apply to this item. All path item properties can be styled.

AVG group item

An AVG group is used to apply transformations to the children. The AVG group item has the following properties:

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.

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 which determines the created AVG item. AVG supports the following types:

• Path
• Group
• Text

opacity

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

style

The named AVG style to apply to this item. All group item properties may be styled.

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.

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. The AVG text item has the following properties:

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.1",
  "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.

style

The named AVG style to apply to this item. All text item properties may be styled.

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:

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\>" 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:

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.

Last updated: Nov 28, 2023