Viewport Object in the Data-binding Context (APL 1.1 to 2023.2)


(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)

The data-binding context includes a viewport property that describes the operating characteristics of the display device.

Viewport property example

For example, the viewport on the original Echo Show reports the following properties:

{
  "viewport": {
    "width": 1024,
    "height": 600,
    "pixelWidth": 1024,
    "pixelHeight": 600,
    "shape": "rectangle",
    "dpi": 160,
    "theme": "dark",
    "mode": "hub"
  }
}

Your skill can use conditional logic to provide different responses for different viewports.

Properties

The following properties are defined in the viewport property.

Property Type/Values Description
dpi Integer Pixel density of the viewport.
height Integer Height of the viewport in dp.
mode Mode The operating mode
pixelHeight Integer Height of the viewport in pixels.
pixelWidth Integer Width of the viewport in pixels.
shape round or rectangle Shape of the viewport.
width Integer Width of the viewport in dp.
theme light or dark The preferred color scheme

dpi

The display-independent pixel (dp) measurement of a screen is an artificial value that represents the visual size of the screen assuming that the screen is held at a mobile-phone viewing distance and has a pixel density of approximately 160 pixels per inch (the original iPhone screen was 163 pixels per inch). Two screens viewed at the same distance with the same physical size have approximately the same dp dimensions regardless of the actual pixel density of the screen.

The dots-per-inch (dpi) of a viewport is an artificial value that reflects the visual size of a point or pixel relative to the observer, and it does not match the actual pixels-per-inch size of the screen. The formula for dpi is:

dpi = 160 * (pixelSize / dpSize)

The following DPI values are supported: 120, 160, 213, 240, 320, 480,

In practice the manufacturer selects the dpi size of the screen based on physical dimensions and expected viewing distance, then calculates the dpSize based on that dpi. For example, manufacturers recommend a 1080p television watching distance of approximately twice the diagonal measurement of the television screen, regardless of the actual screen size. Because the apparent visual size of the TV to the viewer is constant, all 1080p televisions have dpi=320, with pixelHeight of 1080 and height of 540.

Shape

The shape of the screen is set to either round or rectangle.

Height and width

The height and width properties are set to the current display-independent pixel measurements of the screen. You should not assume that these are fixed values for a particular device. The height and width reflect the current orientation of a screen. Tablet computers that rotate between landscape and portrait mode report the width and height of the screen appropriate for the mode they are in. For example, a 1024x600 dp tablet will report a width of 1024 in landscape mode and of 600 in portrait mode.

mode

The mode property describes the expected use of the device. The mode property is assigned one of the following values:

Value Description Common input types Examples
auto Used by the driver in a vehicle Touch Automobile dashboard, built-in aircraft display
hub A table-top or fixed-position devices Touch (when close) Amazon Echo Show, counter-top appliance
mobile A handheld device carried by the user Touch Mobile phone, tablet computer
pc A desktop or laptop computer Keyboard, mouse, trackpad Desktop, laptop computer
tv A television or projected display Remote control Television, billboard

The input types listed in the table above are representative and not guaranteed to exist for a particular device mode.

A single device may report different modes at different times. For example, a tablet computer reports as a "mobile" device at most times, but might report as a "hub" device when it is docked in a docking station. Proximate devices often report as different modes. For example, in an automobile the device built into the dashboard would report as "auto", the device installed in the ceiling behind the driver for passengers would report as "tv", and the mobile phone held by a passenger would report as "mobile".

The list of modes might change. When you use mode in conditional logic, assume that the property could return an unrecognized value. Always provide a default definition for any properties or components that depend upon mode.

Pixel height and width

The pixelHeight and pixelWidth properties are set to the current pixel measurements of the screen. The pixelHeight and pixelWidth reflect the current orientation of a screen. Tablet computers that rotate between landscape and portrait mode report the pixelHeight and pixelWidth of the screen appropriate for the mode they are in. For example, a 1024x600 dp tablet will report pixelWidth of 1024 in landscape mode and 600 in portrait mode.

Theme

The theme reflects the basic color scheme in use on the device. The theme is a string value. You can set the theme in the APL document in the theme property. If it is not set in the document, the device sets it to either "light" or "dark":

  • light: Dark text drawn on a light background
  • dark: Light text drawn on a dark background

You can use the theme when you define styles in your document or package. For example::

{
  "styles": {
    "styledText": {
      "values": [
        {
          "color": "${viewport.theme == 'dark' ? 'white' : 'black'}"
        }
      ]
    },
    "styledFrame": {
      "values": [
        {
          "backgroundColor": "${viewport.theme == 'dark' ? '#096484' : '#74B6CF'}"
        }
      ]
    }
  }
}

In your document, you can choose to ignore the theme entirely or override the device-supplied value with a custom them. For example, this document creates a custom "fancy" theme:

{
  "type": "APL",
  "version": "2024.2",
  "theme": "fancy",
  "styles": {
    "styledText": {
      "description": "A text style that selects colors based on the light, dark, and fancy themes",
      "values": [
        {
          "color": "white"
        },
        {
          "when": "${viewport.theme == 'light'}",
          "color": "black"
        },
        {
          "when": "${viewport.theme == 'fancy'}",
          "color": "red"
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Text",
      "style": "styledText"
    }
  }
}

This approach provides flexibility when the styles and resources are moved to an imported APL package. Then the document author can easily switch between various custom appearances with a single theme choice.


Was this page helpful?

Last updated: Nov 28, 2023