OK, can we please draw something on the display now? Not just yet. Sorry. We're close. Very close. Just one more item to talk about - the Group.

Bitmap and Palette work together to actually make colored pixels. They both get sent to a TileGrid, which allows for some fancy slicing and dicing of the bitmap (if you want to). You can have more than one TileGrid. To collect them all together for final display, you put them into a Group. You can even add a Group to a Group. This allows for some really fancy nesting and drawing.

So let's talk about the Group class. It's actually not that complex.

Group Adding/Removing

The Group class is pretty simple. It's just a collection of TileGrids that you have created. It also allows for nesting other Groups (subgroups) within a Group.

Add items to the Group using append() or insert(). The append() command adds the item to the end while the insert() command allows specifying an index location. You can also change an item directly using index notation, ex: group[index] = tilegrid.

Remove items using pop() or remove(). The pop() command can take an index to pop the ith item, otherwise it removes the last one. The remove() command allows specifying the specific item within the Group to remove.

Group Position

The Group will appear on the screen rooted at the location you specify with x and y. All the items in the Group are positioned relative to this root location (remember TileGrid has x and y also). 

Group Scale

You can also scale the entire contents of the Group using scale. This is a simple integer scaling factor. 1 is normal, 2 is twice as big, etc.

Group Visibility

The hidden property of the Group can be used to set whether the contents of the Group are to be shown or not. Set True to hide (won't be shown) or False to show. By default, this is set to False so items are shown.

Group Content Limits

In older versions of CircuitPython Group was restricted to a maximum number of items. That number was specified by the user code so enough memory space would be created.

However, newer releases allow updating the group to grow as new items are appended so there isn't a specific maximum any longer.

Summary

The Group is what we will finally show on our Display. The end result looks something like this:

This shows a notional Group located at (x, y) on the Display. It contains 3 TileGrids of differing size, shape, and location. Note that the TileGrid locations, specified by their own (x, y) values, are relative to the Group. The values can be negative, like the x value for [1]. Also note how the TileGrid stored in Group index [2] overlaps and is shown above the TileGrid stored in index [0]. This is how "z ordering" works within a Group.