​

Display

The Toit SDK includes support for simple user interfaces on displays. We highlight in this section the basic functions of display use. You can also learn more about the different fonts available in the SDK by studying the font basics.

These examples assume you have installed the pixel_display package into your project. See the Packages quick start guide for information on getting started with packages.

You will also need at least one display driver, for example the SSD1306 driver which is also available as a package, called ssd1306. A color TFT driver that supports many common displays is available in the toit-color-tft and can be installed as the color-tft package.

Getting the display driver and PixelDisplay object

Both the color-tft and ssd1306 packages have some helpful examples which you can see by cloning the github repos linked above. We will assume that you have a get_display.toit file in your project, which might look something like the following. Details will depend on your hardware configuration, in particular which pins and bus you are using to connect your display.

Example contents of get_display.toit

Display architecture

A display will be an subclass of PixelDisplay. These are created with named constructors.

PixelDisplay.two-color for black/white displays.

PixelDisplay.three-color for black/white/red displays (usually e-paper).

PixelDisplay.four-gray for 4-tone grayscale displays (usually e-paper).

PixelDisplay.true-color for color displays like the ones supported by the color-tft driver.

A display maintains a tree of objects that it is currently displaying. These objects are called Elements. As in HTML, one of the popular elements is called Div and it is primarily used to group other elements. The main element for displaying text is called Label.

Elements are mutable objects that represent a shape on the display. For example a geometric shape or a piece of text. Together, the elements added to a display describe a scene.

To update the display, you add or remove elements, or modify the existing elements. When you have made your changes you update the physical display by calling the draw method on the display object.

Normally you will import all the common elements into your namespace with an import like import pixel-display show * The true-color displays use web-like six-digit hex color codes in the style 0xRRGGBB, while other displays have useful constants like BLACK, and WHITE, which can be imported with import pixel-display.two-color show *.

Write with built-in sans font

Let us start with a simple example using a Label element. In this example we use the sans10 font, which is a simple ASCII-only font that is built in to the Toit SDK and does not need to be imported with a package.

We build up a 'scene' consisting of only one text element, and immediately render it to the screen with draw. Afterwards we exit the program, which (depending on the driver) leaves the image on the screen. In this example there is no way to update the scene later, since the program has terminated.

When creating an element to add to the scene there are a huge number of parameters to specify. This includes the color, the orientation, the font, and the coordinate system. We combine almost all these parameters into an immutable object called a style.

In the above example we created a style that draws in black, and uses the built-in sans10 font for text objects. Often styles are used with elements using maps that are reminiscent of CSS.

Using additional fonts

More fonts are available in the packages font-x11-adobe, font-clear, font-clearly-u, and font-tiny packages.

Once you have installed the package in your project, import specific fonts from font-x11-adobe with:

Learn more about all available fonts here.

Using icons

All Material Design icons are available for use in Toit programs.

Updating the display

In order to update the display we can build up a scene, then create a loop that updates the scene as new data arrives. Here is a bigger example that subscribes to an MQTT topic for its weather information, and uses the local time to update a digital clock on the same display.

This example also shows the use of a style built up with maps, to let multiple elements be styled with the same parameters. We can use the syntax --id="my-name" to given an element a name, much like the HTML syntax <div id="my-name">. Similarly, we can give an element a class with --classes=["my-class"], which is analogous to the HTML syntax <div class="my-class">. We don't use --class because that is a reserved keyword in Toit.

A composite style like this for the entire display must be applied to the display with display.set-styles [STYLE] before the display is drawn.

Weather station example screenshot
Weather station example screenshot