APL VectorGraphic (APL 1.7)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

A VectorGraphic displays a scalable vector graphic image defined in a package or loaded from a URL. Use the Alexa Vector Graphic (AVG) format to define the graphics.

Important: VectorGraphic requires APL 1.1 or later. Provide an alternate experience for devices running older versions of APL.

Properties
- height and width
- align
- scale
- source
Actionable properties
Touchable properties
AVG object parameters
VectorGraphic examples
Related topics

Properties

The VectorGraphic component has the following properties:

All actionable component properties
All touchable component properties
All base component properties
The VectorGraphic properties listed in following table. See the meaning of the columns.

Property	Type	Default	Styled	Dynamic	Description
`align`	Alignment	center	Yes	Yes	Alignment of the vector graphic within the component.
`scale`	Scale	none	Yes	Yes	How the vector graphic will scale up or down within the component.
`source`	URL or name	<none>	No	No	The URL or direct reference to a vector graphic.

In addition to these properties, you can pass parameters specific to the AVG object.

When the VectorGraphic is the source or target of an event, the following values are reported in event.source or event.target:

{
  // VectorGraphic-specific values
  "type": "VectorGraphic",
  "url": URL,          // The URL of the vector graphic

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

height and width

When source is a URL, the component should also define the width and height property. When they are not defined, they default to 100 pixels.

When source is a reference to a local package or in the graphics property of the document, you can set set height and width to auto. This uses the height and width defined in the vector graphic object.

align

Positions the VectorGraphic within the component. Set to one of the following:

Name	Description
`bottom`	Align to the bottom and center horizontally.
`bottom-left`	Align the bottom-left corners
`bottom-right`	Align the bottom-right corners
`center`	Center horizontally and vertically.
`left`	Align to the left side and center vertically.
`right`	Align to the right side and center vertically.
`top`	Align to the top and center horizontally.
`top-left`	Align the top-left corners
`top-right`	Align the top-right corners

scale

Scales the vector graphic within the component. Set to one of the following.

Name	Description
`none`	Don't scale the graphic. The align property positions the graphic in the bounding box. The portions of the graphic that fall outside of the bounding box are clipped.
`fill`	Scale the graphic non-uniformly so that the width matches the bounding box width and the height matches the bounding box height.
`best-fill`	Scale the graphic uniformly up or down so that the entire graphic covers the bounding box. The "align" property positions the scaled graphic within the bounding box.
`best-fit`	Scale the graphic uniformly up or down so that the entire graphic fits within the bounding box. The `align` property positions the scaled graphic within the bounding box.

source

Defines the location of the vector graphic data. Set the source to one of the following:

A name defined in the graphics property of your document or an imported package.
A URL that points to a vector graphic definition

Actionable properties

A VectorGraphic is an actionable component. The component inherits all of the actionable properties.

Because the VectorGraphic component doesn't have intrinsic key handlers, the component receives keyboard focus only when you define at least one of the following handlers:

Actionable component onFocus
onBlur
handleKeyDown
handleKeyUp
Touchable component onDown
onPress

If none of the handlers are defined, the VectorGraphic never receives keyboard focus.

Touchable properties

A VectorGraphic is a touchable component. The component inherits all of the touchable properties.

For details about the source event generated when the user taps the component, see the properties in Touchable Component Properties. A VectorGraphic component uses the following specific values:

event.source.type = "VectorGraphic"
event.source.value = Boolean    // The checked state of the vector graphic

The VectorGraphic component adds an additional viewport property to the event:

"event": {
  "viewport": {
    "x": Number,       // X-position of the event in the viewport (internal drawing units)
    "y": Number,       // Y-position of the event in the viewport (internal drawing units)
    "width": Number,   // Width of the viewport (internal drawing units)
    "height": Number,  // Height of the viewport (internal drawing units)
    "inBounds": Boolean,  // True if the event is within the viewport bounds
  }
}

The AVG displayed inside the bounding box for the VectorGraphic component can be smaller or larger than the VectorGraphic itself:

Use the event.viewport.inBounds property to determine whether the event occurred within the transformed bounds of the AVG.
Use the event.inBounds property to determine whether the event occurred within the bounds of the VectorGraphic compnent.

Any combination can occur. An event can be within the VectorGraphic component and outside of the AVG, or outside of the VectorGraphic component and inside of the AVG.

AVG object parameters

Alexa Vector Graphic (AVG) objects can accept parameters. You use parameters to pass colors or specific values (such as rotation) into the graphic. The parameter values are passed as normal properties on the VectorGraphic component itself. For example, if you have a graphic that takes fillColor as a parameter, you can render it with:

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "fillColor": "#ffff00"
}

You can pass both explicit properties (such as the fillColor above) and styled properties. For example, to make a battery that changes color in the disabled state, define this style:

{
  "styles": {
    "batteryStyle": {
      "values": [
        {
          "fillColor": "#ffff00"
        },
        {
          "when": "${state.disabled}",
          "fillColor": "#ff00ff"
        }
      ]
    }
  }
}

Then use the style in the VectorGraphic component:

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "style": "batteryStyle"
}

For details about the format to define a vector graphic, see Vector Graphic Format.

VectorGraphic examples

Basic VectorGraphic example

The following example illustrates a VectorGraphic that displays the AVG called iconWifi3 in a 100x100 box:

{
  "type": "VectorGraphic",
  "source": "iconWifi3",
  "width": 100,
  "height": 100,
  "scale": "best-fit"
}

Toggle button VectorGraphic example

A VectorGraphic component is a touchable component. This means the component responds to pointer events. The following example demonstrates how to create a toggle button using the onPress handler.

{
  "type": "APL",
  "version": "2024.3",
  "graphics": {
    "ToggleButton": {
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "On"
      ],
      "width": 150,
      "height": 90,
      "items": [
        {
          "type": "path",
          "description": "Background shape",
          "pathData": "M45,88 A43,43,0,0,1,45,2 L105,2 A43,43,0,0,1,105,88 Z",
          "stroke": "#979797",
          "fill": "${On ? 'green' : '#d8d8d8' }",
          "strokeWidth": 2
        },
        {
          "type": "group",
          "description": "Button",
          "translateX": "${On ? 60: 0}",
          "items": {
            "type": "path",
            "pathData": "M45,82 A36,36,0,0,1,45,8 A36,36,0,1,1,45,82 Z",
            "fill": "white",
            "stroke": "#979797",
            "strokeWidth": 2
          }
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "VectorGraphic",
      "source": "ToggleButton",
      "bind": {
        "name": "IsOn",
        "value": false
      },
      "On": "${IsOn}",
      "onPress": {
        "type": "SetValue",
        "property": "IsOn",
        "value": "${!IsOn}"
      }
    }
  }
}

Slider bar VectorGraphic example

The following example illustrates how to create a slider bar by using the onDown, onMove, and onUp handlers:

{
  "type": "APL",
  "version": "2024.3",
  "graphics": {
    "Slider": {
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "ButtonPosition",
        "ShowButton"
      ],
      "width": 150,
      "height": 90,
      "scaleTypeWidth": "stretch",
      "items": [
        {
          "type": "path",
          "description": "Slider Background",
          "pathData": "M45,55 a10,10,0,0,1,0,-20 l${width-90},0 a10,10,0,0,1,0,20 Z",
          "stroke": "#979797",
          "fill": "#d8d8d8",
          "strokeWidth": 2,
          "opacity": 0.4
        },
        {
          "type": "path",
          "description": "Slider Fill",
          "pathData": "M45,55 a10,10,0,0,1,0,-20 l${ButtonPosition *(width-90)},0 a10,10,0,0,1,0,20 Z",
          "stroke": "#979797",
          "fill": "#88e",
          "strokeWidth": 2
        },
        {
          "type": "group",
          "description": "Button",
          "translateX": "${ButtonPosition * (width - 90)}",
          "opacity": "${ShowButton ? 1 : 0}",
          "items": {
            "type": "path",
            "pathData": "M45,82 a36,36,0,0,1,0,-76 a36,36,0,1,1,0,76 Z",
            "fill": "#88e",
            "stroke": "white",
            "strokeWidth": 6
          }
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "VectorGraphic",
      "source": "Slider",
      "scale": "fill",
      "width": "100%",
      "bind": [
        {
          "name": "Position",
          "value": 0.50
        },
        {
          "name": "OldPosition",
          "value": 0.50
        },
        {
          "name": "ShowButton",
          "value": false
        }
      ],
      "ButtonPosition": "${Position}",
      "ShowButton": "${ShowButton}",
      "onDown": [
        {
          "type": "SetValue",
          "property": "ShowButton",
          "value": true
        },
        {
          "type": "SetValue",
          "property": "OldPosition",
          "value": "${Position}"
        },
        {
          "type": "SetValue",
          "property": "Position",
          "value": "${0, Math.clamp((event.viewport.x - 45) / (event.viewport.width - 90), 1)}"
        }
      ],
      "onUp": [
        {
          "type": "SetValue",
          "property": "ShowButton",
          "value": false
        },
        {
          "type": "SetValue",
          "description": "Reset the position if we release the pointer at some far location",
          "when": "${!event.inBounds}",
          "property": "Position",
          "value": "${OldPosition}"
        }
      ],
      "onMove": {
        "type": "SetValue",
        "property": "Position",
        "value": "${0, Math.clamp((event.viewport.x - 45) / (event.viewport.width - 90), 1)}"
      }
    }
  }
}

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023