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:

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


Prev Table of Contents Next

This book is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license.