Controllers¶
A viewer, by itself, cannot be interacted by events; it is a static element. On the other hand,
a Controller
is a dynamic element that does not have a geometric representation
and is not able to draw itself on the screen.
To provide functionality to a viewer, or to provide drawing features to a controller, Pyglet-gui mixes both.
This section introduces the API for controllers.
Controller¶
-
class
pyglet_gui.core.
Controller
¶ A controller is an abstract class that represents something that can be controlled.
The main functionality of a controller is to attach itself to a list of controllers of the
ControllerManager
.-
set_manager
()¶ Sets its manager and calls:
manager.add_controller(self)
When mixing a Controller with a Viewer, the controller has to be the first parent-class or you have to write a custom
set_manager()
.
This way, the
ControllerManager
can dispatch calls when it handles events from the Pyglet’s window. To a controller receive events (e.g. “on_press”), it has to have the method implemented (i.e. the manager useshasattr()
to decide if it sends the event to the controller or not). The signature of the method must be the same same as of Pyglet (or, if you want, the oneControllerManager
calls).To receive mouse events, the controller has to define
hit_test(x, y)()
, which returns True if the point (x, y) is inside the controller and False otherwise.-
Two state controller¶
The simplest example of a controller is one that flips between two states.
Pyglet-gui provides a simple abstraction of such behavior in the TwoStateController
.
-
class
pyglet_gui.controllers.
TwoStateController
¶ A
Controller
with two possible values characterized by the read-only propertyis_pressed
. This controller accepts the following arguments:Parameters: - on_press – An optional callback function of one boolean argument that is called when the controller changes state.
- is_pressed – An optional boolean for deciding the state on initialization.
-
is_pressed
¶ True if in one state, False in the other.
This controller has the method
-
change_state
()¶ Flips the state of the controller and calls on_press if it is defined.
Continuous state controller¶
Another example of a useful controller is a controller with a continuous set of values within an interval.
Pyglet-gui provides a simple abstraction of such behavior in the ContinuousStateController
.
-
class
pyglet_gui.controllers.
ContinuousStateController
¶ A
Controller
with a state in a continuous interval [min_value, max_value] characterized by the read-only propertyvalue
.Parameters: - value – The initial value. Default to 0
- min_value – Default to 0.0
- max_value – Default to 1.0
- on_set – An optional callback function of one float argument that is called when the controller changes value.
-
value
¶ The value of the controller. A read-only property.
This controller has the method
-
set_value
()¶ The setter for the value. Calls on_set if it is defined. The value must belong to [min_value, max_value].
Options and selectors¶
One useful GUI less trivial example of a controller is selector: a menu with a set of options, and the user
can choose one and only one.
Pyglet-gui provides an abstraction of such behavior in the Option
and
Selector
.
-
class
pyglet_gui.controllers.
Option
¶ A
Controller
with a name and a parent selector. The name is used as an id in the parent selector. This controller is initialized by a name and a parent:Parameters: - name – Mandatory string
- parent – Mandatory
Selector
.
and has one method
-
select
()¶ Makes him the current selection of the parent.
-
class
pyglet_gui.controllers.
Selector
¶ An abstract class with a set of options labeled by a string. The arguments are
Parameters: - options – Mandatory list of strings identifying the options.
- labels – Optional list of strings with the same length of options labeling the options.
- on_select – Optional callback function that will receive one argument, the selected option name.
- selected – Optional string (belonging to “options” setting a initially-selected item.
This class has two methods:
-
select
()¶ Selects the option name and, if defined, calls on_select.
-
deselect
()¶ Deselects the current selected option, if any is selected.