Skip to main content
Version: 4.16

Widgets and Containers

This section of the documentation will go over two of the most fundamental concepts of building a TouchGFX application: widgets and containers. These are two of the building blocks you will be using throughout the development of your UI. Both include premade components supplied with TouchGFX, while also being open-ended enough to support the creation of custom implementations.


TouchGFX and the TouchGFX Designer tool supplies numerous standard widgets which users can freely use to build their UI, such as TextArea, Button and TextureMapper. But on a fundamental level, a widget in TouchGFX is simply an abstract definition of something that can be drawn on the screen and can be interacted with.

A Button widget with an Image widget as background

Using TouchGFX Designer, users can add any widgets they want to their screens and customize them how they want with the supplied properties specific to each widget. Widgets can also be grouped by using the different types of containers that TouchGFX also supplies.

You can also add widgets in user code if you want by using the add(widget_instance_name); function or adding it to a container by using the containers add function e.g. myContainer.add(widget_instance_name);. The order in which you add the widgets will determine the z-order. The widget added last will appear front-most on the screen.

The coordinates of a widget are always relative to its parent node which is either the root container (the screen) or a container.

Further reading
You can create your own widgets to meet any specific need you might have. Read more on this in the Custom Widgets section.


A container is a component in TouchGFX that can contain child nodes, such as widgets and other containers.

In TouchGFX Designer, containers are found under the Containers category in the Widgets tab and adding widgets to a containers is done by dragging widgets into the container in the tree view.

The z-order of children is determined by the order in which children are added to the container - the child added last will appear front-most on the screen.

Since the position of widgets in TouchGFX is defined relative to their parents, changing the position of a parent container will also move the children accordingly.

Containers act as viewports, meaning that only the parts of the children that intersect with the geometry of the container will be visible.

In the animation below, you can see how the viewport aspect of containers work. First we see the outline of the container of which the button is a child:

A Container acting as a viewport

Further reading
You can create your own container to meet any specific need you might have. Read more on this in the Custom Containers section.