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
  • height
  • item(s)
  • parameters
  • scaleTypeHeight & scaleTypeWidth
  • type
  • version
  • viewportHeight
  • viewportWidth
  • width
• AVG Path Item
  • fillOpacity
  • fill
  • pathData
  • strokeOpacity
  • stroke
  • strokeWidth
• AVG Group Item
  • opacity
  • rotation, pivotX, pivotY
  • scaleX & scaleY
  • translateX & translateY
  • item(s)
• AVG Inflation Algorithm

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:

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:

• Path
• Group

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:

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:

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:

• Path
• Group

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.

---

---

Last updated: Nov 28, 2023