APL VectorGraphic


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.

Properties

The VectorGraphic component has the following properties:

Property Type Default Styled Dynamic Description

align

Alignment

center

Yes

Yes

Alignment of the vector graphic within the component.

onFail

Array of commands

[ ]

No

No

Command or commands to run when the source fails to load.

onLoad

Array of commands

[ ]

No

No

Command or commands to run after the source loads.

parameters

Map of parameters

{}

No

Yes

Optional map of parameters to pass to the vector graphic.

scale

Scale

none

Yes

Yes

How the vector graphic scales up or down within the component.

source

URL or name

<none>

No

Yes

The URL or direct reference to a vector graphic.

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 these properties aren't defined, they default to 100 pixels.

When source is a reference to a local package or a graphic defined in the graphics property of the document, you can 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 values shown in the following table.

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

onFail

Commands to run when the requested URL source fails to load.

The handler runs one time when the source fails to load. After the handler runs, the component is considered invalid.

Setting a new value to the sources property can trigger the handler again. The onFail handler runs at most one time for any new source value.

The onFail handler doesn't affect the display status of the component and the display status doesn't affect the handler. For example, when the display property for the VectorGraphic component is invisible the component takes up space but doesn't display. The device still attempts to load the graphic and runs the commands in onFail if the graphic source fails to load.

The onMount handler for the component runs regardless of whether onFail runs. The onMount handler runs in this scenario because the component can mount and display before or after the component loads the graphic source.

The onFail handler generates an event with the following form.

"event": {
  "source": {
    "type": "VectorGraphic",
    "handler": "Fail",
    ...                     // Component source properties
  },
  "error": STRING,          // The reason of failure
  "errorCode": Number       // Error identifier
}

Refer to Event source for a description of event.source properties.

The onFail event handler runs in fast mode in the component data-binding context.

onLoad

Commands to run after the requested URL source loads.

Setting a new value to the sources property can trigger the handler again. The onLoad handler runs at most one time for any new source value.

The onLoad handler doesn't affect the display status of the component and the display status doesn't affect the handler. For example, when the display property for the Image component is invisible the component takes up space but doesn't display. The device still attempts to load the graphic and runs the commands in onLoad after the graphic source loads.

The onMount handler for the component runs regardless of whether onLoad runs. The VectorGraphic component can mount and display before or after the component loads the graphic source.

The event generated in case of a successful load has the following form.

"event": {
  "source": {
    "type": "VectorGraphic",
    "handler": "Load",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

The onLoad event handler runs in fast mode in the component data-binding context.

parameter, parameters

The parameters property is a map of string names to values which correspond to parameters in the parameters for the source vector graphic. The keys and values of the map have data-binding applied at execution time.

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

The following example shows a VectorGraphic with the source set to a dynamic value. When the user clicks the button, the SetValue command updates the GraphicIndex value, which then changes the graphic displayed.


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:

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 to pass colors or other values such as rotation. You can pass these parameters in one of two ways:

  • Pass a map of your parameters to the parameters property on the component.
  • Set the parameters directly on the VectorGraphic component.

For example, assume you have a graphic that accepts a FillColor parameter.

The following shows how to use the parameters map to pass a value to FillColor.

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "parameters": {
    "FillColor": "#ffff00"
  }
}

Alternatively, the following is also valid.

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

You can't combine these two methods for passing parameters. If you provide the parameters map, any additional properties on the VectorGraphic aren't interpreted as parameters for the graphic.

You can pass both explicit properties (such as the FillColor shown previously) and styled properties.

The following example shows a style that changes the graphic color when the component has the disabled state.

{
  "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 shows 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.


Slider bar VectorGraphic example

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



Was this page helpful?

Last updated: Feb 29, 2024