peng3d.gui.widgets - 2D GUI Widget Base classes

class peng3d.gui.widgets.BasicWidget(name: Optional[str], submenu: SubMenu, window: Any = None, peng: Any = None, *, pos: Union[List[float], Callable[[float, float, float, float], Tuple[float, float]], layout.LayoutCell], size: Union[List[float], Callable[[float, float], Tuple[float, float]], None] = None, order_key: Optional[int] = 0, style: Optional[Dict[str, Union[float, str, Type[Borderstyle]]]] = None)

Basic Widget class.

pos may be either a list or 2-tuple of (x,y) for static positions or a function with the signature window_width,window_height,widget_width,widget_height returning a tuple.

size is similar to pos but will only get window_width,window_height as its arguments.

Commonly, the lambda lambda sw,sh,bw,bh: (sw/2.-bw/2.,sh/2.-bh/2.) is used to center the widget.

Additionally, an instance of a subclass of LayoutCell may be passed as pos. Note that this will automatically override size as well, unless size is also supplied.

The actions available may differ from widget to widget, by default these are used:

• press is called upon starting to click on the widget
• click is called if the mouse is released on the widget while also having been pressed on it before, recommended for typical button callbacks
• context is called upon right-clicking on the widget and may be used to display a context menu
• hover_start signals that the cursor is now hovering over the widget
• hover is called every time the cursor moves while still being over the widget
• hover_end is called after the cursor leaves the widget
• statechanged is called every time the visual state of the widget should change

Deprecated since version 1.12: The window and peng parameters are deprecated and will be removed in peng3d 2.0. They are no longer needed and should be removed from existing code.

Changed in version 1.12: It is no longer necessary to register widgets using addWidget(), widget registration is now automatically performed by widgets themselves.

IS_CLICKABLE = False

Class attribute used to signal if widgets of this class are usually clickable.

This attribute is used to fill the initial value of enabled and can therefore be overridden on a widget-by-widget basis.

Note that leaving this set to False will prevent most mouse-related actions from being triggered. This is due to internal optimization and the main benefit of leaving this option off.

clickable

Property used for determining if the widget should be clickable by the user.

This is only true if the submenu of this widget is active and this widget is enabled.

The widget may be either disabled by setting this property or the enabled attribute.

delete()

Deletes resources of this widget that require manual cleanup.

Currently removes all actions, event handlers and the background.

The background itself should automatically remove all vertex lists to avoid visual artifacts.

Note that this method is currently experimental, as it seems to have a memory leak.

draw() → None

Draws all vertex lists associated with this widget.

enabled

Property used for storing whether or not this widget is enabled.

May influence rendering and behavior.

Note that the widget will be immediately redrawn if this property is changed.

getState() → str

Returns the current state of the widget.

One of "pressed", "hover", "disabled" or "idle". Note that some information may be lost by getting this state, for example it is not possible to know if the widget is hovered or not if "pressed" is returned. However, this should not be a problem for most intended uses of this method.

on_redraw() → None

Callback to be overridden by subclasses called if redrawing the widget seems necessary.

Note that this method should not be called manually, see redraw() instead.

pos

Property that will always be a 2-tuple representing the position of the widget.

Note that this method may call the method given as pos in the initializer.

The returned object will actually be an instance of a helper class to allow for setting only the x/y coordinate.

This property also respects any Container set as its parent, any offset will be added automatically.

Note that setting this property will override any callable set permanently.

redraw() → None

Triggers a redraw of the widget.

Note that the redraw may not be executed instantly, but rather batched together on the next frame. If an instant and synchronous redraw is needed, use on_redraw() instead.

registerEventHandlers()

Registers event handlers used by this widget, e.g. mouse click/motion and window resize.

This will allow the widget to redraw itself upon resizing of the window in case the position needs to be adjusted.

size

Similar to pos but for the size instead.

visible

Property used for storing whether or not this widget is enabled.

May influence rendering and behavior.

Note that the widget will be immediately redrawn if this property is changed.

class peng3d.gui.widgets.Background(widget: peng3d.gui.widgets.BasicWidget)

Class representing the background of a widget.

Note that if a background is used as the background of a SubMenu, the SubMenu instance itself should be passed as the widget.

This base class does not do anything.

init_bg() → None

Called just before the background will be drawn the first time.

Commonly used to initialize vertex lists.

It is recommended to add all vertex lists to the submenu.batch2d Batch to speed up rendering and preventing glitches with grouping.

is_hovering

Read-only helper property for easier access.

Equivalent to widget.is_hovering.

peng

Property for accessing the parent widget’s instance of peng3d.peng.Peng.

pressed

Read-only helper property for easier access.

Equivalent to widget.pressed.

redraw_bg() → None

Method called by the parent widget every time its Widget.redraw() method is called.

reg_vlist(vlist: pyglet.graphics.vertexdomain.VertexList) → None

Registers a vertex list to the internal list.

This allows the class to clean itself up properly during deletion, as the background would still be visible after deletion otherwise.

submenu

Property for accessing the parent widget’s submenu.

window

Property for accessing the parent widget’s window.

peng3d.gui.widgets.DEFER_BG = <peng3d.gui.widgets._DeferBackgroundSentinel object>

Sentinel object that may be passed instead of an actual background to signify that the background will be set later.

Differs from passing None, since None will cause an EmptyBackground to be unnecessarily created, while DEFER_BG simply does nothing.

Note that if the actual background is not set before the first render, a TypeError will be raised.

class peng3d.gui.widgets.Widget(name: Optional[str], submenu: SubMenu, window: Any = None, peng: Any = None, *, pos: Union[List[float], Callable[[float, float, float, float], Tuple[float, float]], layout.LayoutCell], size: Union[List[float], Callable[[float, float], Tuple[float, float]], None] = None, bg: peng3d.gui.widgets.Background = None, min_size: Optional[List[float]] = None)

Subclass of BasicWidget adding support for changing the Background.

If no background is given, an EmptyBackground will be used instead.

on_redraw()

Draws the background and the widget itself.

Subclasses should use super() to call this method, or rendering may glitch out.

setBackground(bg: peng3d.gui.widgets.Background) → peng3d.gui.widgets.Background

Sets the background of the widget.

This may cause the background to be initialized.

class peng3d.gui.widgets.EmptyBackground(widget: peng3d.gui.widgets.BasicWidget)

Background that draws simply nothing.

Can be used as a placeholder.