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:

Property Type Default Description
description String "" Optional description of this vector graphic.
height Absolute Dimension REQUIRED The height of the graphic.
item(s) Array of AVG items [] An array of drawing items. Each item is either a GROUP or a PATH
parameters Array of AVG parameters [] An array of parameter values that can be set on the AVG object.
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.
type "AVG" REQUIRED The type of vector graphic.
version "1.0" REQUIRED The current release version of the AVG standard.
viewportHeight Number <height> The height of the viewport
viewportWidth Number <width> The width of the viewport
width Absolute Dimension REQUIRED The width of the graphic.

This example defines a simple diamond filled with red:

{
  "type": "AVG",
  "version": "1.0",
  "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(s)

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. There are currently two types:

parameters

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

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

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

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

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

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

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

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

scaleTypeHeight & scaleTypeWidth

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

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

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

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

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

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.0. 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.0 was introduced with APL 1.1.

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

Property Type Default Description
type "path" REQUIRED Must be set to "path".
fillOpacity Number 1 The opacity of the path fill.
fill Color transparent The fill color.
pathData String REQUIRED The path drawing data.
strokeOpacity Number 1 The opacity of the path stroke.
stroke Color transparent The color used to draw the stroke.
strokeWidth Number 1 The width of the path stroke.

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

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.

fill

The color used to fill the path. If not specified, the fill is not be drawn.

pathData

A string containing one or more path commands, as defined by the SVG "d" specification. Briefly, the path commands are:

Command Parameters Description
M, m (x,y)+ Move to the beginning of the next sub-path in absolute coordinates. Additional pairs are implicit "L" commands. The "m" variant uses relative coordinates
L, l (x,y)+ Draw a line from the current location to the new location in absolute coordinates. Pairs may be repeated for additional lines. The "l" variant uses relative coordinates
H, h x+ Draw a horizontal line in absolute (H) or relative (h) coordinates
V, v y+ Draw a vertical line in absolute (V) or relative (v) coordinates
C, c (x1,y1,x2,y2,x,y)+ Draw a Bézier curve from the current point to x,y, using x1,y1,x2,y2 as control points. Uses absolute (C) or relative (c)
S, s (x2,y2,x,y)+ Draw a smooth Bézier curve from the current point to x,y using x2,y2 as the control point at the end of the curve. Uses absolute (S) or relative (s) coordinates
Q, q (x1,y1,x,y)+ Draw a quadratic Bézier curve to the coordinates x,y with x1,y1 as the control point. Absolute (Q) or relative (q) coordinates.
T, t (x,y)+ Draw a smooth quadratic Bézier curve to the coordinate x,y, where the control point carries over from the previous curve. Absolute (T) or relative (t) coordinates
A, a Z, z (rx ry angle large-arc-flag sweep-flag x y)+ Draw an elliptical arc curve to the coordinates x,y. The radii of the ellipse are rx, ry. The rotation of the ellipse is angle. The flags choose which segment of the arc to draw and which direction. Absolute (A) or relative (a) coordinates. Close the current subpath with a straight line between the start point and end point. Note that fill will not be affect by closing a subpath, but stroke will.

Refer to the SVG specification for the authoritative definition.

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.

stroke

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

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 is used to apply transformations to the children. The AVG group item has the following properties:

Property Type Default Description
type "group" REQUIRED Must be set to "group".
opacity Number 1.0 The opacity of the group.
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)
item(s) Array of AVG items [] Array of child drawing items.

The transformations are applied in the order of scale, rotate, and then translate.

opacity

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

rotation, pivotX, pivotY

The rotation angle of the group, in degrees about the point pivotX, pivotY.

scaleX & scaleY

The scaling of the group.

translateX & translateY

The translation of the group.

item(s)

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. There are currently two types:

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 and paths, applying data-binding.