Elements of a Control Tile

Each tile is represented by a Control. When we create instances of a Control, we get to define a Template and a device type for that Control, plus we get to react to an Action when one is raised.

Template

The element that determines what a tile looks and works like is the template. As the name suggests, it provides a general structure for a tile, where you get to fill in the details, such as the text that appears in the tile.

Templates are defined via subclasses of ControlTemplate, where the specific subclass determines the type of interactivity:

• ToggleTemplate allows the user to toggle between two states (e.g., on and off)
• RangeTemplate allows the user to choose a value within a range, reminiscent of a SeekBar
• ToggleRangeTemplate allows the user to do both of those: turn something on/off and, if on, control the value within a range
• TemperatureControlTemplate supports toggling between multiple distinct modes (e.g., heat, cool, “eco”), in addition to wrapping one of the aforementioned template types (e.g., allow the user to toggle between heating and cooling, plus specify a value within a temperature range)

All of those have an associated state that the user is modifying via the tile. The assumption is that your app has the ability to determine the current state of whatever the tile controls and pass along the user’s requested changes to that state.

There is also a StatelessTemplate. While you can find out about taps on this type of tile (via actions, covered in the next section), there is no state that your app — or the device controls framework — needs to track.

Action

Your choice of template in turn drives how the user can interact with it. Your app will find out about the user’s choices via an action. Actions are represented by subclasses of ControlAction. The subclasses represent the type of data that is being tracked as state for this tile; your app, upon receiving the action, is supposed to change the state of the associated device to that new value:

Action Class	State Data Type	Associated Templates
BooleanAction	boolean	ToggleTemplate, ToggleRangeTemplate, TemperatureControlTemplate
FloatAction	float	RangeTemplate, ToggleRangeTemplate, TemperatureControlTemplate
ModeAction	int	TemperatureControlTemplate

There is also a CommandAction, emitted by a StatelessTemplate, that just tells you that the user clicked on the tile. The idea is that you might use this to send some command to the device that is not necessarily tied to any state.

Device Type

Our choice of “device type” for a tile primarily controls an icon that goes in the upper-start corner of the tile. Secondarily, it might have other visual effects, such as changing the default color that gets used.

A device type is represented by an Int value. DeviceTypes contains a list of Int constants for the supported device types. This is a long list, containing both obvious device types (lights, thermostats), esoteric ones (hood, mop, drawer), and generic ones (on/off, lock/unlock, temperature).

In reality, not every one of these gets a distinct icon, at least in stock versions of Android 11.

Control

All of the above get wrapped up into a Control. You create instances of a Control via builders. Principally, you will use Control.StatefulBuilder to not only provide the details of the control but also the current state value associated with the device (e.g., is it on or off for a ToggleTemplate). There is also a Control.StatelessBuilder that you will use for a specific initial-loading scenario (but, despite the name, this is only somewhat related to StatelessControl).