Overview of the API¶
This document gives an overview of how Pyglet-gui works and what you can do with it.
A Viewer is characterized by a rectangular bounding box that implements abstract methods
Graphical Elements such as textures, inside it.
In Pyglet-gui, a GUI organizes viewers in a tree: every viewer has a
Container (a subclass of Viewer with children viewers)
and the root of the tree is a
ViewerManager, a special
container without parent. This is small variation of the composite pattern.
This structure is essentially used to minimize the number of operations in the drawing Batch; Pyglet-gui provides two orthogonal ways to operate on the batch: the top-down and bottom-up:
- Top-down: when a container wants to reload itself in the batch (e.g. in the initialization of the
- Bottom-up: when a single
Viewerwants to reload itself (e.g. when a
Controllerchanged a viewer’s state).
Pyglet-gui abstracts most of these concepts by a simple interface. The procedure can be decomposed in three steps,
as exemplified in
Button source code:
def change_state(self): self._is_pressed = not self._is_pressed self.reload() self.reset_size()
- the state of the Viewer changes, and that requires a new appearance;
reload()the graphics of the Viewer;
reset_size()reset size of the viewer bounding box.
If the Viewer changed size when it became pressed, the method
is propagated to the parent container and in the tree up to the container that didn’t changed size,
which means that a relayout of the GUI is only made to a certain level in the tree, minimizing
Batch operations. The complete references of this API can be found in
Theme and Graphics¶
Pyglet-gui has a graphics API for handling vertex lists and vertex attributes:
The developer defines a
Theme from a dictionary, and viewers select
the part of the theme they need using a path computed from the viewer’s current state,
These templates are able to generate
that are used by
Viewers to compose their appearance.
A Controller represents something that can have behavior, such as something triggered by Pyglet events.
A handler in a controller is just a method “on_*”: the ControllerManager only handles specific Pyglet events
hasattr() to check which controllers receive those events.
In the directory “examples” you can find examples of how to instantiate GUIs and how to use the Pyglet-gui to create elements with custom functionality.
get_path(): used to select the path on the
unload_graphics(): used to load and unload
layout(): used to position the
Graphical Elementsin the correct place;
compute_size(): used to compute the size of the Viewer from the graphics it contains;
- on_*: used to handle events.
Existing user interfaces¶
Below is a list of the existing elements in Pyglet-gui. Elements that are not links are not documented yet and most probably are not yet covered by a Test Case.
- Graphics: a viewer with a graphic element from the theme.
- Spacer: an empty viewer for filling space in containers.
- Label: a viewer that holds text.
- Document: a viewer that holds Pyglet documents (optionally with a scrollbar).
- Vertical: widgets inside are arranged vertically.
- Horizontal: widgets inside are arranged horizontally.
- Grid: widgets inside are arranged in a grid (you provide a matrix of them).
- Frame: a wrapper that adds a graphical frame around a viewer.
- Scrollable: a wrapper with scrollable content.
- End-user controllers:
Button: a On/Off button with a label and graphics placed on top off each other.
- OneTimeButton: a Button which turns off when is released.
- Checkbox: a Button where the label is placed next to the graphics (and graphics is a checkbox-like button).
- FocusButton: a Button that can have focus and is selectable with TAB.
- HorizontalSlider: an concrete implementation of a Slider, in horizontal position.
- TextInput: a box for writing text.