Groups allow you to manage the elements that are rendered on the display. You can think of them like layers that can be removed or displayed. You can even have a Group inside of another Group and that is exactly what we are going to do but first we need to set a few things up.

Define a Group

To define a display group we want to use the displayio.Group() function. 

Here is an example of some groups that we would want to setup for our UI.

# ------------- Display Groups ------------- #
splash = displayio.Group() # The Main Display Group
view1 = displayio.Group(x=0, y=40) # Group for View 1 objects
view2 = displayio.Group(x=0, y=40) # Group for View 2 objects
view3 = displayio.Group(x=0, y=40) # Group for View 3 objects

# ------------- Display Groups ------------- #
splash = displayio.Group() # The Main Display Group
view1 = displayio.Group(x=0, y=40) # Group for View 1 objects
view2 = displayio.Group(x=0, y=40) # Group for View 2 objects
view3 = displayio.Group(x=0, y=40) # Group for View 3 objects

This sets up one Main display group called splash and three other groups that will be used to display selectable tab views. Notice how we have set the view groups to be moved down 40 pixels. This is so that these groups will start their display coordinates from x=0, y=0 just underneath where our Tab buttons will be rendered. It will just make the layout of those pages a little easier to manage.

Adding to a Group

Now that we have a few groups, we will want to assign them to our splash group so that they can be part of the display image. This is done by using .append() to add you object to the list of objects in the group.

Here is how it looks to add our three view groups to our main group:

splash.append(view1)
splash.append(view2)
splash.append(view3)

splash.append(view1)
splash.append(view2)
splash.append(view3)

Later, we will be adding objects like buttons, text, and images to these Groups.

Other helpful functions

here are a few other helpful functions that we will be using to manage our groups.

• pop() - This is basically used to delete a Group. We will use this later for switching Icon images.
  • group.pop() - This deletes the first element in group.
  • group.pop(2) - This deletes the third element in group.
  • view3.pop(-2) - This deletes the second to last element in the view3 Group.
• remove(i) - This is used to remove a Group or Object from a Group. It will not delete the Object or Group, but it can be used to temporarily remove that element for the display.
  • group.remove(object) - This will remove the element object from group
  • splash.remove(view2) - This will remove the view2 Group from the splash Group

For CircuitPython 5 and greater, there is a new function called hidden and it can be used to hide a Group or Object in a Group.

• hidden = bool - Set this to True to hide all elements of a group.
  • splash[4].hidden = True - This will hide the 5th Group or Object in the splash Group.
  • splash[4].hidden = False - This will show the 5th Group or Object in the splash Group.

While this function will hide something from view, it will not always bring it back unless the display is refreshed. For this reason, we will be using another method for showing and hiding Groups.

Hide and Show a Group

The biggest reason we want to use Groups is that we can use them like Layers to show and hide making it possible to have multiple screen views. For this example we are going to use buttons that will let us switch between view1, view2, and view3. This will be done by showing one of those pages while hiding the other two. To make this easy, and because we will be doing it a lot, we will make a function for hiding a group and another for showing a group.

# ------------- Layer Function ------------- #
# Set visibility of target object inside of layer
def layerVisibility(state, layer, target):
    try:
        if state == "show":
            time.sleep(0.1)
            layer.append(target)
        elif state == "hide":
            layer.remove(target)
    except ValueError:
        pass

# use the function like this:
layerVisibility("hide", splash, view3)
layerVisibility("show", splash, view2)

# ------------- Layer Function ------------- #
# Set visibility of target object inside of layer
def layerVisibility(state, layer, target):
    try:
        if state == "show":
            time.sleep(0.1)
            layer.append(target)
        elif state == "hide":
            layer.remove(target)
    except ValueError:
        pass

# use the function like this:
layerVisibility("hide", splash, view3)
layerVisibility("show", splash, view2)

We will go over how this function gets used in the Usage section.

For more information on Groups, check out the link below for the CircuitPython documentation.