Managers¶

In Pyglet-gui, each independent GUI is a Manager, a subclass of both ViewerManager and ControllerManager.

This section provides the relevant references for understanding how Manager works and how you can use it.

This section is the most complex of this documentation because it glues different APIs together. The references of the classes are themselves divided in APIs, so it is hopefully easier to understand.

Viewer Manager¶

ViewerManagerGroup¶

Each Manager is independent of each other, but they are drawn on the same window, so, they need different vertex groups to know which one is drawn on top. A ViewerManagerGroup is defined for that:

class pyglet_gui.manager.ViewerManagerGroup¶

A Pyglet’s ordered group, i.e. a drawing group that preserves ordering with a unique ordering on instances of ViewerManagerGroup.

This group uses its own order, own_order, to distinguish itself from other Pyglet’s Ordered groups.

own_order¶: The same value as order, used for comparisons between ViewerManagerGroup.

This group defines __eq__, __lt__ and __hash__ that compare against ViewerManagerGroup using own_order and against other ordered groups using order.

The different ViewerManagerGroup don’t know each other, but always know if they are on top of all.

is_on_top()¶: Returns true if the particular instance is on top amongst all instances of ViewerManagerGroup.

To set this group to be the top group, use pop_to_top():

pop_to_top()¶

Sets own_order to the highest value amongst all instances of ViewerManagerGroup, ensuring the instance becomes the top.

ViewerManager¶

class pyglet_gui.manager.ViewerManager¶

A manager of Viewers. A ViewerManager is a subclass of pyglet_gui.containers.Wrapper that exposes important features of Pyglet-gui.

Because it is a container, it is part of the tree structure used by Pyglet-gui to draw viewers. However, this container is special in the sense that it does not have a parent, and thus it only pyglet_gui.core.Viewer.reset_size() with reset_parent=False, i.e. it only uses the top-down drawing.

One consequence is that because no one sets its position, it sets its own position, from a position computed from get_position().

Because it is the root of the tree, it exposes attributes required for drawing to its viewers. They are the pyglet_gui.theme.theme.Theme, the Batch and batch groups.

theme¶

The pyglet_gui.theme.theme.Theme of this manager. A read-only property defined in the initialization.

One theme can be shared among different ViewerManagers.

batch¶

The Batch of the manager. A read-only property defined on the initialization.

If no batch is provided in initialization, this Manager defines its own batch and exposes a draw() method.

A Pyglet Batch can be shared among ViewerManagers and is exposed by each viewer by the method pyglet_gui.core.Managed.get_batch().

Because Pyglet-gui Theme API uses groups for drawing, the ViewerManager is responsible for defining such groups to its viewers.

The first group required is for the ViewerManager itself, such that different ViewerManagers can be drawn in the same window. This is implemented in the root_group:

root_group¶: A ViewerManagerGroup used by ViewerManagers to decide which manager is on top of each other (on drawing). It is exposed as a read-only property.

Because there can be several managers on the same window, the viewer implements the method pop_to_top():

pop_to_top()¶: Calls ViewerManagerGroup.pop_to_top().

For drawing viewers, this manager has 4 sub-groups exposed by the attribute group:

group¶

A dictionary of 4 key-strings: ‘panel’, ‘background’, ‘foreground’, ‘highlight’ mapping to 4 pyglet.graphics.OrderedGroup with orders 10, 20, 30 and 40 respectively.

When a graphic element is generated by the Viewer, the viewer has to decide which group to use to that element. This property is exposed in each viewer by the method pyglet_gui.core.Managed.get_batch().

window¶

A Pyglet window where the ViewerManager lives, exposed as a property.

The manager uses Pyglet’s window to know where it has to be positioned, and to assign itself as an handler.

This property is writable to assign another window to the manager.

get_position()¶

Computes and returns its position (x, y) on its window.

Used with pyglet_gui.core.Viewer.set_position() to set the position of this manager in the window.

Controller Manager¶

class pyglet_gui.manager.ControllerManager¶

A controller manager is the class responsible for managing Pyglet-gui Controllers.

It has a list of controllers assigned to him and is responsible for calling its handlers.

controllers¶: The list of controllers assigned to him. Exposed as a read-only property.

add_controller()¶: Appends the controller to controllers.

remove_controller()¶: Removes the controller from controllers.

This manager assumes the user is only interested in using one controller at the time. It tracks down the mouse position and tests when the mouse entered in a controller bounding box, saving that controller as the current “hovering” controller.

When the mouse is pressed, the “hovering” controller also becomes the “focus” controller. These are unique within a manager because Containers don’t overlap viewers.

The class exposes two methods for this behaviour:

set_focus()¶: Sets the controller to be the focus of the manager. If controllers have the method, it calls on_lose_focus and on_gain_focus of the old focus and new focus respectively.

set_hover()¶: Sets the controller to be the hover of the manager. If controllers have the method, it calls on_lose_highlight and on_gain_highlight of the old hover and new hover respectively.

The focus controller is the only controller to receive keystrokes and other events.

In this manager, the keystroke TAB and SHIFT+TAB are handled to navigate (to the front and to the back) in the list of controllers, to give focus to them. This is useful for keyboard driven GUIs.

This manager has two other special controllers, the “wheel target” and “wheel hint” (in case wheel target don’t handle the event), used to handle mouse wheel events. This is useful for allowing scrollbars to receive wheel events without requiring the user to click on them to “focus it”.

set_wheel_target()¶: Sets the wheel target to be the controller. The controller has to have the method on_mouse_scroll.

set_wheel_hint()¶: Sets the wheel hint to be the controller. The controller has to have the method on_mouse_scroll.

Manager¶

class pyglet_gui.manager.Manager¶

The manager is the Pyglet-gui main element for initializing a new GUI in Pyglet-gui. It is a subclass of both ViewerManager and ControllerManager which overrides some of the on_* methods to give some functionality to the ViewerManager.

Parameters:

content – The content of this manager. An instance of Viewer.
theme – The Theme of this manager. An instance of Theme.
window – The window of this manager. An instance of Pyglet Window.
batch – An optional Batch for this manager. If set, must be an instance of Pyglet Batch.
group – An optional Group, parent of the group this manager uses. Must be a Pyglet Group
is_movable – If False, this manager is not movable.
anchor – A anchor option to position this manager in relation to the window. Default to ALIGN_CENTER.
offset – The offset of this manager in relation to the anchor point.

Besides the implementation of ViewerManager and ControllerManager, the manager implements its own movability: it can be dragged if the parameter ‘is_movable’ is true.