Especially useful widgets¶
Glooey comes with a wide variety of built-in widgets, but you can go a long way with just a few. This tutorial introduces some of the most fundamental widgets to give you a feel for what’s available and how to make GUIs that are more “real” than the Getting started example. These introductions are very brief, but you can find complete documentation for every widget in the API documentation.
Keep in mind that the built-in widgets are unstyled, so they’re all kinda ugly and/or aggressively minimalist 1. Glooey’s philosophy is that subclassing widgets is the easiest and most powerful way to control how they look, so all the built-in widgets try to remain blank slates in terms of style. The Stylizing widgets tutorial has more information on how to change what the built-in widgets look like.
Note
All the examples in this tutorial leave out the code to create the GUI and run the pyglet event loop. Those steps are explained in the Getting started tutorial. If you want to see those steps, you can download the script associated with each example.
Grid — organize widgets¶
The Grid
widget is a container that organizes widgets into
a grid. Along with HBox
and VBox
, it is one of the most common ways to
control how widgets are arranged:
In this example, the grid infers how many rows and columns to make from the
indices provided to the add()
calls. You can also explicitly tell
the grid how many rows and columns to make:
# Initialize a grid with 3 rows and 4 columns.
grid = glooey.Grid(3, 4)
# Resize the grid to have 5 rows and 6 columns.
grid.num_rows = 5
grid.num_cols = 6
By default, the grid distributes space evenly between all its rows and columns, but you can also control the size of any row or column. The most common thing to do is to set the size of a row or column to 0 to make it just large enough to fit all its widgets:
grid.set_row_height(1, 0)
grid.set_col_width(1, 0)
HBox — horizontal layout¶
HBox
arranges widgets horizontally. It’s essentially a simplified Grid with
only one row:
VBox — vertical layout¶
VBox
arranges widgets vertically. It’s essentially a simplified Grid with
only one column:
Label — show text¶
The Label
widget displays text:
By default, the label widget will only put line breaks where you tell it to
(i.e. where there are \n
characters in the text). However, you can have it
wrap text to fit a particular width by specifying the line_wrap
option:
This feature has one big caveat: the text will not fill more than the specified width, even if there is free space available to it. In other words, there’s no way to say “wrap to fill the whole screen”. Instead, like in this example, you have to say something like “wrap to fill 640 px”. This caveat is due to a limitation in how glooey assigns space to widgets 2.
Background — tile images¶
The Background
widget fills in space using tiled images.
You can think of it like a picture frame: you specify images for the corners
and edges, and it tiles the edges to fill in all the space it needs to.
This example doesn’t adequately reflect how flexible the background widget is. In addition to what you see above, it can:
Grow horizontally or vertically or in both directions
Accommodate any combination of edge, corner, and center images
Use solid colors to make fills and outlines
But the true power of the background widget is how easily it can be customized
and incorporated into other widgets. Those topics are beyond the scope of this
tutorial, but it’s worth mentioning that you should very rarely need to use the
set_appearance()
method. See the
tutorials on Stylizing widgets and Composing widgets for more details.
The caveat with the background widget is that the images you give it must fill
their whole textures in the dimensions being tiled. Usually this means images
with power-of-two sizes (e.g. 16, 32, 64 px) that were loaded using
pyglet.resource.texture()
. The reason for this caveat is that the
background widget tiles images by manipulating their texture coordinates. This
approach is very efficient, but it doesn’t work if the image is loaded into a
texture with extra space around the edges.