Overview of the API

This document gives an overview of how Pyglet-gui works and what you can do with it.

Pyglet-gui uses Viewers for defining appearance and Controllers for defining behaviour. For instance, a Button is a subclass of a Viewer (for draw) and of a Controller (for behaviour).

Viewers

A Viewer is characterized by a rectangular bounding box that implements abstract methods to draw Graphical Elements such as textures, inside it.

In Pyglet-gui, a GUI organizes viewers in a tree: every viewer has a parent 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 Manager).
• Bottom-up: when a single Viewer wants to reload itself (e.g. when a Controller changed 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()

1. the state of the Viewer changes, and that requires a new appearance;
2. reload() the graphics of the Viewer;
3. reset_size() reset size of the viewer bounding box.

If the Viewer changed size when it became pressed, the method reset_size() 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 Viewer.

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, get_path().

This Theme is constructed out of a nested dictionary by having Parsers interpreting the dictionary’s content and populating the Theme with Templates.

These templates are able to generate Graphical Elements that are used by Viewers to compose their appearance.

Controllers

A Controller represents something that can have behavior, such as something triggered by Pyglet events.

Pyglet-gui uses a ControllerManager for handling all window events in the GUI, and the manager uses these events to call the correct Controllers' handlers.

A handler in a controller is just a method “on_*”: the ControllerManager only handles specific Pyglet events and uses hasattr() to check which controllers receive those events.

Examples

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.

In fact, all Pyglet-gui user interfaces are examples, since they are just subclasses of Controller, Viewer, or both, that implement custom methods:

• get_path(): used to select the path on the Theme;
• load_graphics() and unload_graphics(): used to load and unload Graphical Elements;
• layout(): used to position the Graphical Elements in 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.

Viewers:

• 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).

Controllers:

• TwoStateController: a controller with two states.
• ContinuousStateController: a controller with a float value state.
• Slider: a ContinuousStateController with continuous or discrete states and 3 graphic elements: a bar, a knob and markers.

Containers:

• 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.