Display API

Variable: display

The Display API provides the ability to manipulate the device's physical display behavior.

Note: AOD properties and methods cannot be used without the access_aod permission. Apps and clocks using AOD cannot be sideloaded (except to the simulator) and cannot published in the Fitbit App Gallery without prior authorization from Fitbit.

import { display } from "display";

display.addEventListener("change", () => {
   if (display.on) {
     // start sensors
   } else {
     // stop sensors
   }
});

Interface: Display

A Display object represents the properties and events related to the physical display of the device.

Properties

readonly aodActive

boolean

New in SDK 4.1

Whether the display is currently in Always-On Display (AOD) mode.

The value true means that AOD mode is currently active, and false means that it is currently inactive. If aodAllowed is false this will be false even if AOD mode is currently active.

When this property is true, your clock or app MUST comply with AOD mode restrictions (on-pixel ratio and screen refresh rate).

aodAllowed

boolean

New in SDK 4.1

Whether the current app is opted-in to AOD mode.

Apps may set this to true to signal that they are able to enter AOD mode, or set this to false (the default) to signal that they aren't able to enter AOD mode.

If aodEnabled is true but aodAllowed is false, the built-in AOD clock will be shown when entering AOD mode.

Setting this to true has no effect for a clock if aodEnabled is false: AOD mode will not be entered.

This property can be set to true for an application to enable AOD independently of the system wide AOD setting.

If your app or clock does not have the access_aod permission, this will always return false and may not be set to true.

readonly aodAvailable

boolean

New in SDK 4.1

Whether Always-On Display (AOD) mode is supported by the current device.

The value true means that AOD mode is supported, and false means that it is not supported.

readonly aodEnabled

boolean

New in SDK 4.1

Whether AOD mode is currently enabled system-wide.

If the system AOD setting is enabled, this will be true, otherwise false.

autoOff

boolean

Whether the display should turn off automatically after a certain time.

The value true means that the display will turn off automatically after a certain time, and false means that the display will remain in its current state until explicitly changed.

NOTE: The duration of the auto-off timer is managed by the system and is not configurable using this API.

Starting with SDK version 4.0, on devices with AMOLED (active-matrix organic light-emitting diode) displays, this property will always be set to true. Any attempt to modify it will be ignored by the system and a message will be printed in the developer console.

brightnessOverride

"dim" or "normal" or "max" or undefined

New in SDK 4.0

Forced brightness of the display. It might be set to dim, normal, max, similar to the values that might be selected from Settings menu. This value is ignored when the display is not on. When the value is undefined, the brightness is not overridden (it is set and managed by the system). The display will automatically choose the highest value whether it is provided by the Settings menu, or via brightnessOverride.

on

boolean

Whether the display is on or off.

The value true means that the display is on, and false that the display is off. This property is read/write, so it can be used to query the state of the display and/or change its state.

If your app or clock is not AOD mode enabled, this will return false when AOD mode is active.

onchange

((this: Display, event: Event) => any) or undefined

Event handler for the change event.

Methods

addEventListener()

addEventListener(type: "change", listener: (this: Display, event: Event) => any)

Returns: void

Add an event handler for the change event.

This event is emitted whenever the display is turned on or off, including changes to [on] by your own code.

It is also emitted when AOD mode is entered/exited.

NOTE: When the display is turned on via an external input (e.g. screen tap, button push), there is no guarantee of ordering between that input event (e.g. document.onkeydown) and this change event.

poke()

Returns: void

Turn the display on and restart the autoOff timer, if enabled.

Calling this function will ensure that the display remains on for at least the duration of the auto-off timeout. If autoOff is set to false, this function simply turns the display on.

This function will exit AOD mode if it is currently active.

DisplayBrightnessValue

String: "dim" | "normal" | "max"

New in SDK 4.0

List of brightness values display might be set to.

Device API

Document API