glooey.dialogs.YesNoDialog

class glooey.dialogs.YesNoDialog(*args, **kwargs)[source]

Bases: glooey.dialogs.ButtonDialog

Custom Attributes:

YesButton(*args, **kwargs)

NoButton(*args, **kwargs)

Inherited from ButtonDialog

Box

alias of glooey.containers.Grid

Content

alias of glooey.text.Label

custom_autoadd_content

If a Content inner class is specified, automatically instantiate it and add it to the frame.

Buttons([default_cell_size])

Inherited from Frame

Box

alias of glooey.containers.Grid

Content

alias of glooey.text.Label

Decoration

The widget that will appear in the background of the frame.

custom_box_layer

The z-order for the contents of the frame (i.e.

custom_decoration_layer

The z-order for the frame's decorations (i.e.

custom_autoadd_content

If a Content inner class is specified, automatically instantiate it and add it to the frame.

custom_alignment

How the widget should align itself within the space assigned to it.

Inherited from Widget

custom_alignment

How the widget should align itself within the space assigned to it.

custom_padding

How much space the widget should keep free around its edges.

custom_horz_padding

How much space the widget should keep free around its left and right edges.

custom_vert_padding

How much space the widget should keep free around its top and bottom edges.

custom_left_padding

How much space the widget should keep free on its left side.

custom_right_padding

How much space the widget should keep free on its right side.

custom_top_padding

How much space the widget should keep free on its top side.

custom_bottom_padding

How much space the widget should keep free on its bottom side.

custom_size_hint

The user-set minimum size for this widget.

custom_width_hint

The user-set minimum width for this widget.

custom_height_hint

The user-set minimum height for this widget.

custom_grab_mouse_on_click

Indicate that the widget should automatically grab the mouse when being clicked.

custom_propagate_mouse_events

Whether or not this widget should propagate mouse events to its children.

Public Properties

yes_button

no_button

response

Inherited from ButtonDialog

content

Return the widget being displayed in the frame.

buttons

Inherited from Frame

box

Return the widget holding the content of the frame.

content

Return the widget being displayed in the frame.

decoration

Return the widget appearing in the background of the frame.

Inherited from Widget

is_root

True if this is the root of the widget hierarchy.

is_hidden

True if this widgets or one of its parents is hidden.

is_visible

False if this widgets or one of its parents is hidden.

is_enabled

True if the widget can be clicked on.

is_disabled

True if the widget can be clicked on.

is_attached_to_gui

True if the widget is part of the widget hierarchy.

size_hint

Return the user-set minimum dimensions of this widget.

padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

event_types

parent

Return this widget's parent, or None if this widget hasn't been attached to the GUI yet.

root

Return the top of the widget hierarchy, or None if this widget hasn't been attached to the GUI yet.

window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn't been attached to the GUI yet.

batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn't been attached to the GUI yet.

group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn't been attached to the GUI yet.

rect

Return the vecrec.Rect indicating where this widget is located on the screen.

width

Return the width of the widget.

height

Return the height of the widget.

width_hint

Return the user-set minimum width for this widget.

height_hint

Return the user-set minimum height for this widget.

claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

claimed_size

Return the width and height needed to render this widget.

claimed_width

Return the width needed to render this widget.

claimed_height

Return the width needed to render this widget.

padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget's content plus its padding.

horz_padding

Return the padding on the left and right sides of this widget.

vert_padding

Return the padding on the top and bottom of this widget.

left_padding

Return the padding on the left side of this widget.

right_padding

Return the padding on the right side of this widget.

top_padding

Return the padding on the top of this widget.

bottom_padding

Return the padding on the bottom of this widget.

total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

alignment

Return how this widget will be positioned within the space assigned to it.

rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

grab_mouse_on_click

propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

Public Methods:

__init__(*args, **kwargs)

Initialize the widget.

open(gui)

on_click_yes(widget)

on_click_no(widget)

get_yes_button()

set_yes_button(button)

get_no_button()

set_no_button(button)

get_response()

Inherited from ButtonDialog

__init__(*args, **kwargs)

Initialize the widget.

add(widget)

Add a widget to the frame.

clear()

Remove any widgets from the frame.

get_content()

Return the widget being displayed in the frame.

get_buttons()

Inherited from Dialog

open(gui)

close()

Inherited from Frame

__init__(*args, **kwargs)

Initialize the widget.

add(widget)

Add a widget to the frame.

clear()

Remove any widgets from the frame.

do_claim()

Return the minimum width and height needed to render this widget.

do_regroup_children()

React to changes that might require this widget's children to be regrouped.

get_box()

Return the widget holding the content of the frame.

get_content()

Return the widget being displayed in the frame.

get_decoration()

Return the widget appearing in the background of the frame.

set_decoration(widget)

Set the widget appearing in the background of the frame.

Inherited from Widget

__init__(*args, **kwargs)

Initialize the widget.

__repr__()

Return a succinct string identifying this widget.

__bool__()

Always consider widgets to be "true".

__len__()

Return the number of children this widget has.

__contains__(widget)

Return true if the given widget is one of this widget's children.

hide()

Make the widget invisible.

unhide([draw])

Make the widget visible again.

enable()

Indicate that the widget should react to the mouse.

disable()

Prevent the widget from reacting to the mouse.

do_attach()

React to the widget being attached to the GUI.

do_detach()

React to the widget being detached from the GUI.

do_claim()

Return the minimum width and height needed to render this widget.

do_resize()

React to a change in the widget's size.

do_resize_children()

React to changes that might require this widget's children to be resized.

do_regroup()

React to a change in the widget's pyglet graphics group.

do_regroup_children()

React to changes that might require this widget's children to be regrouped.

do_draw()

Draw any shapes or images associated with this widget.

do_undraw()

Delete any shapes or images associated with this widget.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

get_parent()

Return this widget's parent, or None if this widget hasn't been attached to the GUI yet.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn't been attached to the GUI yet.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn't been attached to the GUI yet.

get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn't been attached to the GUI yet.

get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn't been attached to the GUI yet.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

get_width()

Return the width of the widget.

get_height()

Return the height of the widget.

get_size_hint()

Return the user-set minimum dimensions of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

get_width_hint()

Return the user-set minimum width for this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

get_height_hint()

Return the user-set minimum height for this widget.

set_height_hint(new_height)

Set the minimum height for this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_claimed_height()

Return the width needed to render this widget.

get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget's content plus its padding.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

set_padding([all, horz, vert, left, right, ...])

Set the padding for any or all sides of this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

get_left_padding()

Return the padding on the left side of this widget.

set_left_padding(new_padding)

Set the padding for the left side of this widget.

get_right_padding()

Return the padding on the right side of this widget.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

get_top_padding()

Return the padding on the top of this widget.

set_top_padding(new_padding)

Set the padding for the top of this widget.

get_bottom_padding()

Return the padding on the bottom of this widget.

set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_alignment()

Return how this widget will be positioned within the space assigned to it.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

get_grab_mouse_on_click()

set_grab_mouse_on_click(new_setting)

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

debug_placement_problems([claimed, ...])

Draw boxes showing the widgets assigned, claimed, and content rectangles.

Inherited from EventDispatcher

__init__(*args, **kwargs)

Initialize the widget.

relay_events_from(originator, event_type, ...)

Configure this handler to re-dispatch events from another handler.

start_event(event_type, *args[, dt])

Begin dispatching the given event at the given frequency.

stop_event(event_type)

Stop dispatching the given event.

Inherited from EventDispatcher

register_event_type(name)

Register an event type with the dispatcher.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

set_handler(name, handler)

Attach a single event handler.

pop_handlers()

Pop the top level of event handlers off the stack.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

remove_handler(name, handler)

Remove a single event handler.

dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

event(*args)

Function decorator for an event handler.

Inherited from HoldUpdatesMixin

__init__(*args, **kwargs)

Initialize the widget.

pause_updates()

resume_updates()

discard_updates()

hold_updates()

suppress_updates()

Private Properties

Inherited from Widget

_Widget__num_children

Return the number of children attached to this widget.

_Widget__padding

Inherited from EventDispatcher

_event_stack

Private Methods:

Inherited from ButtonDialog

_replace_button(old_button, new_button, on_click)

Inherited from Widget

_repack()

Indicate that the widget's size may have changed, and that the sizes of its children and parents may also need to change in response.

_claim()

Make sure the widget's claim is up-to-date.

_resize(new_rect)

Change the size or shape of this widget.

_realign()

Update the amount of space available for the widget's content, given the amount of space assigned to it by its parent.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

_attach_child(child)

Add a child to this widget.

_detach_child(child)

Detach a child from this widget.

_draw()

Create or update the vertex lists needed to render the widget.

_draw_all()

Draw this widget and all of its children.

_undraw()

Delete the vertex lists being used to render this widget.

_undraw_all()

Undraw this widget and all of its children.

_grab_mouse()

Force all mouse events to be funneled to this widget.

_ungrab_mouse([x, y])

Release the mouse and allow mouse events to be handled as usual again.

_hide_children()

Hide all of the widget's children.

_unhide_children([draw])

Redraw any of the widget's children that were visible before the widget itself was hidden.

_Widget__yield_all_children()

Recursively iterate over all of this widget's children and grandchildren.

_Widget__yield_self_and_all_children()

Recursively iterate over this widget and all of its children and grandchildren.

_Widget__find_children_under_mouse(x, y)

Track and return the children that are under the given mouse coordinate.

_Widget__find_children_under_mouse_after_leave()

Update the list of children under the mouse as the mouse leaves this widget.

_Widget__find_mouse_grabber()

Return which of this widget's children or grandchildren is grabbing the mouse, or None if none of them are.

_Widget__update_rollover_state(new_state, x, y)

Notify anyone who's interested that the mouse just interacted with this widget.

_Widget__get_num_children()

Return the number of children attached to this widget.

_Widget__set_padding([all, horz, vert, ...])

Without repacking, set the four padding attributes (top, left, bottom, right) defined in the Widget class.

Inherited from EventDispatcher

_EventDispatcher__yield_handlers(event_type)

Yield all the handlers registered for the given event type.

Inherited from EventDispatcher

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

_raise_dispatch_exception(event_type, args, ...)

Inherited from HoldUpdatesMixin

_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active.


Box

alias of glooey.containers.Grid

class Buttons(default_cell_size=None)

Bases: glooey.containers.HBox

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'custom_alignment': 'right', '__doc__': None, '__annotations__': {}})
__init__(default_cell_size=None)

Initialize the container.

See add() for more details about the default_cell_size argument.

__iter__()
__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

add(widget, size=None)

Add the given widget to the layout.

The widget will be added to the back of the layout (i.e. right for HBox, bottom for VBox). The size argument specifies how much space (i.e. width for HBox, height for VBox) to allocate for the “cell” that will contain the widget (if you think of the hbox/vbox as a 1-dimensional grid). The size can either be an integer number of pixels or the string 'expand':

  • number of pixels (int): The specified number of pixels will be allocated for the widget, unless that number is smaller than the widget’s minimum size (i.e. its claim). In that case, the widget’s minimum size will be allocated instead (because a widget can’t be smaller than its minimum size). For this reason, size=0 is a common setting meaning: “take as little space as possible”. Of course, you can also specify size=100 to make a cell exactly 100px wide/tall, assuming that the widget in question is smaller than that.

  • 'expand' (str): A special value indicating that the widget should expand to fill any space available to the container but not used by any other cells. For example, imagine you have a HBox that’s 500px wide (or a VBox that’s 500 px tall). If you add two widgets with size='expand', each will get 250 px. If you add one widget with size=100 and two with size='expand', the latter two will get 200px each.

If no size is specified, a default is used. The default can be set (in order of precedence) either via set_default_cell_size(), an argument to the constructor, or the custom_default_cell_size class variable.

Examples:

These are with HBox, but could equivalently be with VBox. Assume for the sake of simplicity that the HBox is 500px wide. Further assume that w1, w2, and w3 are arbitrary widgets with no minimum size (e.g. Placeholder).

In this example, w1 and w2 will both be 250px wide (i.e. half the width of the container):

>>> h1 = glooey.HBox()  # 500px wide
>>> h1.add(w1, size='expand')
>>> h1.add(w2, size='expand')

In this example, w1 will be 100px wide and w2 and w3 will split the remaining space and be 200px each:

>>> h2 = glooey.HBox()  # 500px wide
>>> h2.add(w1, size=100)
>>> h2.add(w2, size='expand')
>>> h2.add(w3, size='expand')
add_back(widget, size=None)

Add the given widget to the back of the layout.

This is an alias for add().

add_front(widget, size=None)

Add the given widget to the front of the layout.

The same as add(), except the widget will be added to the front of the layout (i.e. left for HBox, top for VBox).

add_left(widget, size=None)

Add the given widget to the front of the layout.

The same as add(), except the widget will be added to the front of the layout (i.e. left for HBox, top for VBox).

add_right(widget, size=None)

Add the given widget to the back of the layout.

This is an alias for add().

property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property cell_alignment

Return how widgets are aligned within their cells.

property cell_padding

Return the padding between the cells of this widget, in pixels.

property children

Return the child widgets being organized by this container.

The return value is a tuple so that the list of children won’t be mutable, and so the caller can’t somehow inadvertently change the list of children held by the container.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

clear()

Remove every widget from the layout.

custom_alignment = 'right'

How the widget should align itself within the space assigned to it.

custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_cell_alignment = 'fill'

How widgets are aligned within their cells.

See set_alignment() for more details about this option.

custom_cell_padding = None

The padding between the cells of the grid.

This is distinct from custom_padding, which is the padding around the edge of the grid.

custom_default_cell_size = 'expand'

How much space a cell will consume if no size is specified.

See set_default_cell_size() for more details about this option.

custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

property default_cell_size

Return the default cell size (i.e. a number of pixels or the string 'expand').

Reimplement to either return the row or column widths of the underlying grid.

disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Claim enough space for all the child widgets put together in the direction of the layout (e.g. horizontal for HBox, vertical for VBox) and just enough space for the largest child widget in the opposite direction.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Speed up the search for the child widget under the mouse based

This reimplementation is faster than the default implementation, which simply checks every child widget for collisions with the given mouse coordinate, because it searches underlying the grid layout instead. This takes advantage of the following two facts:

  1. We know that only one widget can be under the mouse, so we can stop the search as soon as we find that widget.

  2. We only need to check for collisions in the direction of the layout (i.e. horizontal for HBox, vertical for VBox), because we know that all the child widgets will overlap in the opposite direction.

do_get_index(row, col)

Given row and columns number of a child widget, return the index of that widget in the 1-dimensional _children data structure.

This would be the column for HBox and the row for VBox.

do_get_row_col(index)

Given the index of a child widget, return its row and column numbers as a tuple.

The “on-axis” number (e.g. column for Hbox, row for VBox) should just be the given index. The “off-axis” number should be 1.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

Allocate space to the child widgets according to how much space they asked for when added to the layout (e.g. their “size”) and how much space they need (e.g. their “claim”).

do_set_row_col_sizes(sizes)

Copy child size information into the underlying grid data structure.

The sizes argument is a dictionary mapping 1-dimensional child indices to the sizes provided by add() (e.g. 0, ‘expand’, etc). This information either needs to be applied to the columns (HBox) or rows (VBox) of the underlying grid data structure.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_cell_alignment()

Return how widgets are aligned within their cells.

get_cell_padding()

Return the padding between the cells of this widget, in pixels.

get_children()

Return the child widgets being organized by this container.

The return value is a tuple so that the list of children won’t be mutable, and so the caller can’t somehow inadvertently change the list of children held by the container.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_default_cell_size()

Return the default cell size (i.e. a number of pixels or the string 'expand').

Reimplement to either return the row or column widths of the underlying grid.

get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, plus the padding between the cells, as a (left, right, top bottom, cell) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

insert(widget, index, size=None)

Insert the given widget at the given position in the layout.

See add() for details about the size argument.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

pack(widget)

Add the given widget to the layout such that it takes as little space as possible.

This is an alias for add(widget, size=0)

pack_back(widget)

Add the given widget to the back of layout such that it takes as little space as possible.

This is an alias for add_back(widget, size=0)

pack_front(widget)

Add the given widget to the front of layout such that it takes as little space as possible.

This is an alias for add_front(widget, size=0)

property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, plus the padding between the cells, as a (left, right, top bottom, cell) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove(widget)

Remove the given widget from the layout.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

replace(old_widget, new_widget)

Remove the given old widget from the layout and replace it with the given new widget.

The new widget will be given the same size (e.g. the size argument to add()) as the old widget. That said, the new widget could still take up a different amount of space, if it’s claim is different. The layout will be repacked automatically if this is the case.

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_cell_alignment(new_alignment)

Specify how widgets should be aligned within their cells.

See set_alignment() for information on the possible values for this setting. Note that a widget’s alignment value just applies to itself, but the “cell alignment” value applies to this container’s children. This is unusual, and brings up the question of what happens when two alignment settings apply to the same child widget:

The answer is that the container’s cell alignment is applied before the alignments of any of its children. This means that container can limit the space available to the children, potentially making the children’s alignment values irrelevant. For example, if the cell alignment is:

  • ‘center’: All children will be centered within their cells, regardless of their individual alignment values. This is because the ‘center’ alignment assigns the minimum possible space to a widget, so there is no room for further alignment.

  • ‘fill horz’: All children will be centered vertically within their cells, but their horizontal alignments will depend on their individual alignment values. For example, children with alignments of ‘top left’, ‘left’, and ‘bottom left’ would all end up centered vertically on the left sides of their cells.

  • ‘fill’: Children will be aligned entirely according to their individual alignment values. This is the default value (unless custom_cell_alignment has been changed) because it provides the most flexibility.

set_cell_padding(new_padding)

Set the padding between the cells of this widget, in pixels.

set_default_cell_size(size)

Set the default cell size.

See add() for more details about this setting.

set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None, cell=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

Content

alias of glooey.text.Label

Decoration = None

The widget that will appear in the background of the frame. Often this is either glooey.images.Background (for variably-sized frames) or Image (for fixed-size frames).

class NoButton(*args, **kwargs)[source]

Bases: glooey.buttons.Button

class Background(**kwargs)

Bases: glooey.images.Background

The default widget class to use for the background in each state.

This default can be overridden for each specific rollover state by the Button.Base, Button.Over, Button.Down, and Button.Off inner classes, although this shouldn’t often be necessary.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.buttons', '__doc__': "\n        The default widget class to use for the background in each state.\n\n        This default can be overridden for each specific rollover state by the \n        `Button.Base`, `Button.Over`, `Button.Down`, and `Button.Off` inner \n        classes, although this shouldn't often be necessary.\n        ", '__annotations__': {}})
__init__(**kwargs)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.buttons'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property appearance
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_bottom = None
custom_bottom_left = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_bottom_right = None
custom_center = None
custom_color = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_htile = 'auto'
custom_image = None
custom_left = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_outline = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right = None
custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_top = None
custom_top_left = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_top_right = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_vtile = 'auto'
custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_appearance()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_outline()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property image
property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_empty
property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property outline
property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_appearance(*, color=None, image=None, center=None, top=None, bottom=None, left=None, right=None, top_left=None, top_right=None, bottom_left=None, bottom_right=None, vtile='auto', htile='auto')
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(new_color)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_image(image)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_outline(new_outline)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

Base = None

The widget class to use for the base-state background.

Down = None

The widget class to use for the down-state background.

class Foreground(text=None, line_wrap=None, **style)

Bases: glooey.text.Label

The widget class to use for the foreground.

Any widget class can be used, but the two most common choices are glooey.text.Label (the default) and Image.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.buttons', '__doc__': '\n        The widget class to use for the foreground.\n\n        Any widget class can be used, but the two most common choices are \n        `Label` (the default) and `Image`.\n        ', '__annotations__': {}})
__init__(text=None, line_wrap=None, **style)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.buttons'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_update_style()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background_color
property baseline
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bold
property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_background_color = None
custom_baseline = None
custom_bold = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_color = 'green'
custom_font_name = None
custom_font_size = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_italic = None
custom_kerning = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_line_spacing = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = ''
custom_text_alignment = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_underline = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background_color()
del_baseline()
del_bold()
del_color()
del_font_name()
del_font_size()
del_italic()
del_kerning()
del_line_spacing()
del_style(style)
del_text()
del_text_alignment()
del_underline()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

disable_line_wrap()
discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw(ignore_rect=False)

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_make_new_layout(document, kwargs)
do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

enable_line_wrap(width)
event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property font_name
property font_size
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_background_color()
get_baseline()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bold()
get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_font_name()
get_font_size()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_italic()
get_kerning()
get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_line_spacing()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_style(style)
get_text()
get_text_alignment()
get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_underline()
get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property italic
property kerning
property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property line_spacing
on_delete_text(start, end)
on_insert_text(start, text)
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background_color(color)
set_baseline(baseline)
set_bold(bold)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(color)
set_font_name(name)
set_font_size(size)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_italic(italic)
set_kerning(kerning)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_line_spacing(spacing)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_style(**style)
set_text(text, width=None, **style)
set_text_alignment(alignment)
set_top_padding(new_padding)

Set the padding for the top of this widget.

set_underline(underline)
set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property text
property text_alignment
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

property underline
unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

class Label(text=None, line_wrap=None, **style)[source]

Bases: glooey.text.Label

__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'custom_text': 'Cancel', '__doc__': None, '__annotations__': {}})
__init__(text=None, line_wrap=None, **style)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_update_style()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background_color
property baseline
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bold
property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_background_color = None
custom_baseline = None
custom_bold = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_color = 'green'
custom_font_name = None
custom_font_size = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_italic = None
custom_kerning = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_line_spacing = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = 'Cancel'
custom_text_alignment = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_underline = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background_color()
del_baseline()
del_bold()
del_color()
del_font_name()
del_font_size()
del_italic()
del_kerning()
del_line_spacing()
del_style(style)
del_text()
del_text_alignment()
del_underline()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

disable_line_wrap()
discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw(ignore_rect=False)

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_make_new_layout(document, kwargs)
do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

enable_line_wrap(width)
event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property font_name
property font_size
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_background_color()
get_baseline()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bold()
get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_font_name()
get_font_size()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_italic()
get_kerning()
get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_line_spacing()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_style(style)
get_text()
get_text_alignment()
get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_underline()
get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property italic
property kerning
property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property line_spacing
on_delete_text(start, end)
on_insert_text(start, text)
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background_color(color)
set_baseline(baseline)
set_bold(bold)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(color)
set_font_name(name)
set_font_size(size)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_italic(italic)
set_kerning(kerning)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_line_spacing(spacing)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_style(**style)
set_text(text, width=None, **style)
set_text_alignment(alignment)
set_top_padding(new_padding)

Set the padding for the top of this widget.

set_underline(underline)
set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property text
property text_alignment
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

property underline
unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

Off = None

The widget class to use for the off-state background.

Over = None

The widget class to use for the over-state background.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'Label': <class 'glooey.dialogs.YesNoDialog.NoButton.Label'>, '__doc__': None, '__annotations__': {}})
__init__(*args, **kwargs)

Create a new button widget.

Any arguments are passed directly to the constructor for the foreground widget.

__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_custom_background_appearances()

Setup the background widgets from parameters found in dynamically named custom_... class variables.

For example, the class variable custom_base_image = ... would call set_appearance(image=...) on the “base” background widget.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_yield_layers()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background
property base_background
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

click()
custom_alignment = 'center'

How the widget should align itself within the space assigned to it.

custom_background_layer = 1

The z-coordinate of the background widget.

You can change this to put the “background” in front of the foreground, which is sometimes desirable.

custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_foreground_layer = 2

The z-coordinate of the foreground widget.

You can change this to put the “background” in front of the foreground, which is sometimes desirable.

custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_image = None

The image to display on the button.

This custom attribute simply sets the image attribute of the foreground widget. Note that this will have any effect if the foreground widget has an image attribute, like Image does.

custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = None

The text to display on the button.

This custom attribute simply sets the text attribute of the foreground widget. Note that this will only have any effect if the foreground widget has a text attribute, like glooey.text.Label does.

custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background()
del_foreground()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

property down_background
enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property foreground
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_base_background()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_down_background()
get_foreground()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_off_background()
get_over_background()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property off_background
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property over_background
property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background(**kwargs)

Set appearance options for any of the background widgets.

This is a convenience method for calling set_appearance() on any of the background widgets. Each keyword argument to this function should either be of the form <rollover> or <rollover>_<kwarg>, where <rollover> is the name of a rollover state and <kwargs> is the name of an argument to the set_appearance() method of the widget representing that state.

Arguments of the <rollover> form specify actual widgets to use for the indicated state. Arguments of the form <rollover>_<kwarg> specify keyword arguments to pass to that widget’s set_appearance() method. You can mix both kinds of arguments.

The following rollover states are understood:

  • base

  • over

  • down

  • off

The <option> names must be valid keyword arguments to the underlying widget’s set_appearance() method. Of course, different widgets will accept different arguments. These arguments also require that the background widgets implement the set_appearance() method. Image and glooey.images.Background both meet this requirement, but widgets derived from other classes may not.

Note that any appearance options not specified will not be displayed. In other words, if you only specify a base rollover state, the other rollover states will be disabled. Or if you only specify edge images, no center images will be displayed. A common mistake is to try to configure the appearance of a button with multiple calls to this method, but this will just result in the last call overriding all the earlier ones.

set_base_background(widget)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_down_background(widget)
set_foreground(widget)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_off_background(widget)
set_over_background(widget)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

class YesButton(*args, **kwargs)[source]

Bases: glooey.buttons.Button

class Background(**kwargs)

Bases: glooey.images.Background

The default widget class to use for the background in each state.

This default can be overridden for each specific rollover state by the Button.Base, Button.Over, Button.Down, and Button.Off inner classes, although this shouldn’t often be necessary.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.buttons', '__doc__': "\n        The default widget class to use for the background in each state.\n\n        This default can be overridden for each specific rollover state by the \n        `Button.Base`, `Button.Over`, `Button.Down`, and `Button.Off` inner \n        classes, although this shouldn't often be necessary.\n        ", '__annotations__': {}})
__init__(**kwargs)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.buttons'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property appearance
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_bottom = None
custom_bottom_left = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_bottom_right = None
custom_center = None
custom_color = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_htile = 'auto'
custom_image = None
custom_left = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_outline = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right = None
custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_top = None
custom_top_left = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_top_right = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_vtile = 'auto'
custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_appearance()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_outline()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property image
property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_empty
property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property outline
property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_appearance(*, color=None, image=None, center=None, top=None, bottom=None, left=None, right=None, top_left=None, top_right=None, bottom_left=None, bottom_right=None, vtile='auto', htile='auto')
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(new_color)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_image(image)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_outline(new_outline)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

Base = None

The widget class to use for the base-state background.

Down = None

The widget class to use for the down-state background.

class Foreground(text=None, line_wrap=None, **style)

Bases: glooey.text.Label

The widget class to use for the foreground.

Any widget class can be used, but the two most common choices are glooey.text.Label (the default) and Image.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.buttons', '__doc__': '\n        The widget class to use for the foreground.\n\n        Any widget class can be used, but the two most common choices are \n        `Label` (the default) and `Image`.\n        ', '__annotations__': {}})
__init__(text=None, line_wrap=None, **style)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.buttons'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_update_style()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background_color
property baseline
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bold
property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_background_color = None
custom_baseline = None
custom_bold = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_color = 'green'
custom_font_name = None
custom_font_size = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_italic = None
custom_kerning = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_line_spacing = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = ''
custom_text_alignment = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_underline = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background_color()
del_baseline()
del_bold()
del_color()
del_font_name()
del_font_size()
del_italic()
del_kerning()
del_line_spacing()
del_style(style)
del_text()
del_text_alignment()
del_underline()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

disable_line_wrap()
discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw(ignore_rect=False)

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_make_new_layout(document, kwargs)
do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

enable_line_wrap(width)
event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property font_name
property font_size
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_background_color()
get_baseline()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bold()
get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_font_name()
get_font_size()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_italic()
get_kerning()
get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_line_spacing()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_style(style)
get_text()
get_text_alignment()
get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_underline()
get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property italic
property kerning
property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property line_spacing
on_delete_text(start, end)
on_insert_text(start, text)
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background_color(color)
set_baseline(baseline)
set_bold(bold)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(color)
set_font_name(name)
set_font_size(size)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_italic(italic)
set_kerning(kerning)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_line_spacing(spacing)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_style(**style)
set_text(text, width=None, **style)
set_text_alignment(alignment)
set_top_padding(new_padding)

Set the padding for the top of this widget.

set_underline(underline)
set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property text
property text_alignment
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

property underline
unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

class Label(text=None, line_wrap=None, **style)[source]

Bases: glooey.text.Label

__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'custom_text': 'Ok', '__doc__': None, '__annotations__': {}})
__init__(text=None, line_wrap=None, **style)

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_update_style()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background_color
property baseline
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bold
property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

property color
custom_alignment = 'fill'

How the widget should align itself within the space assigned to it.

custom_background_color = None
custom_baseline = None
custom_bold = None
custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_color = 'green'
custom_font_name = None
custom_font_size = None
custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_italic = None
custom_kerning = None
custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_line_spacing = None
custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = 'Ok'
custom_text_alignment = None
custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_underline = None
custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background_color()
del_baseline()
del_bold()
del_color()
del_font_name()
del_font_size()
del_italic()
del_kerning()
del_line_spacing()
del_style(style)
del_text()
del_text_alignment()
del_underline()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

disable_line_wrap()
discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw(ignore_rect=False)

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_make_new_layout(document, kwargs)
do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

enable_line_wrap(width)
event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property font_name
property font_size
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_background_color()
get_baseline()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bold()
get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_color()
get_font_name()
get_font_size()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_italic()
get_kerning()
get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_line_spacing()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_style(style)
get_text()
get_text_alignment()
get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_underline()
get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property italic
property kerning
property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property line_spacing
on_delete_text(start, end)
on_insert_text(start, text)
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background_color(color)
set_baseline(baseline)
set_bold(bold)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_color(color)
set_font_name(name)
set_font_size(size)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_italic(italic)
set_kerning(kerning)
set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_line_spacing(spacing)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_style(**style)
set_text(text, width=None, **style)
set_text_alignment(alignment)
set_top_padding(new_padding)

Set the padding for the top of this widget.

set_underline(underline)
set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property text
property text_alignment
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

property underline
unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

Off = None

The widget class to use for the off-state background.

Over = None

The widget class to use for the over-state background.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'Label': <class 'glooey.dialogs.YesNoDialog.YesButton.Label'>, '__doc__': None, '__annotations__': {}})
__init__(*args, **kwargs)

Create a new button widget.

Any arguments are passed directly to the constructor for the foreground widget.

__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_custom_background_appearances()

Setup the background widgets from parameters found in dynamically named custom_... class variables.

For example, the class variable custom_base_image = ... would call set_appearance(image=...) on the “base” background widget.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

_yield_layers()
property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property background
property base_background
property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

click()
custom_alignment = 'center'

How the widget should align itself within the space assigned to it.

custom_background_layer = 1

The z-coordinate of the background widget.

You can change this to put the “background” in front of the foreground, which is sometimes desirable.

custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_foreground_layer = 2

The z-coordinate of the foreground widget.

You can change this to put the “background” in front of the foreground, which is sometimes desirable.

custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_image = None

The image to display on the button.

This custom attribute simply sets the image attribute of the foreground widget. Note that this will have any effect if the foreground widget has an image attribute, like Image does.

custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_text = None

The text to display on the button.

This custom attribute simply sets the text attribute of the foreground widget. Note that this will only have any effect if the foreground widget has a text attribute, like glooey.text.Label does.

custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

del_background()
del_foreground()
disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

property down_background
enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
property foreground
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_base_background()
get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_down_background()
get_foreground()
get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_off_background()
get_over_background()
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property off_background
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

property over_background
property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_background(**kwargs)

Set appearance options for any of the background widgets.

This is a convenience method for calling set_appearance() on any of the background widgets. Each keyword argument to this function should either be of the form <rollover> or <rollover>_<kwarg>, where <rollover> is the name of a rollover state and <kwargs> is the name of an argument to the set_appearance() method of the widget representing that state.

Arguments of the <rollover> form specify actual widgets to use for the indicated state. Arguments of the form <rollover>_<kwarg> specify keyword arguments to pass to that widget’s set_appearance() method. You can mix both kinds of arguments.

The following rollover states are understood:

  • base

  • over

  • down

  • off

The <option> names must be valid keyword arguments to the underlying widget’s set_appearance() method. Of course, different widgets will accept different arguments. These arguments also require that the background widgets implement the set_appearance() method. Image and glooey.images.Background both meet this requirement, but widgets derived from other classes may not.

Note that any appearance options not specified will not be displayed. In other words, if you only specify a base rollover state, the other rollover states will be disabled. Or if you only specify edge images, no center images will be displayed. A common mistake is to try to configure the appearance of a button with multiple calls to this method, but this will just result in the last call overriding all the earlier ones.

set_base_background(widget)
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_down_background(widget)
set_foreground(widget)
set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_off_background(widget)
set_over_background(widget)
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

__annotations__ = {}
__bool__()

Always consider widgets to be “true”.

This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.

__contains__(widget)

Return true if the given widget is one of this widget’s children.

__dict__ = mappingproxy({'__module__': 'glooey.dialogs', 'YesButton': <class 'glooey.dialogs.YesNoDialog.YesButton'>, 'NoButton': <class 'glooey.dialogs.YesNoDialog.NoButton'>, '__init__': <function YesNoDialog.__init__>, 'open': <function YesNoDialog.open>, 'on_click_yes': <function YesNoDialog.on_click_yes>, 'on_click_no': <function YesNoDialog.on_click_no>, 'get_yes_button': <function YesNoDialog.get_yes_button>, 'set_yes_button': <function YesNoDialog.set_yes_button>, 'get_no_button': <function YesNoDialog.get_no_button>, 'set_no_button': <function YesNoDialog.set_no_button>, 'get_response': <function YesNoDialog.get_response>, '__doc__': None, 'yes_button': <property object>, 'no_button': <property object>, 'response': <property object>, '__annotations__': {}})
__init__(*args, **kwargs)[source]

Initialize the widget.

Don’t forget to call this method from subclasses!

__len__()

Return the number of children this widget has.

__module__ = 'glooey.dialogs'
__repr__()

Return a succinct string identifying this widget.

The string includes the widget’s class and a 4-letter identifier to distinguish between different instances of the same class. The identifier is just the four least-significant hex digits of the widget’s address in memory, so while it is very unlikely that two widget’s would have the same identifier, it’s not impossible.

__weakref__

list of weak references to the object (if defined)

_attach_child(child)

Add a child to this widget.

This method checks to make sure the child isn’t already attached to some other widget, tells the child who it’s new parent is, and adds the child to an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore. For example, you would use this method if implementing a

_claim()

Make sure the widget’s claim is up-to-date.

More specifically, this methods updates self.__claimed_width and self.__claimed_height to reflect the current state of the widget and its children, then returns whether or not the claim changed since the last time this method was called. If this function is called more than once within a single repack (a common scenario because every widget depends on the claim of all its children and grandchildren), the first call will update the claim and any subsequent calls will simply return False without recalculating anything.

When the claim needs to be recalculated, the first step is the update the claims made by all the widget’s children, since this widget’s claim will depend on that information. This is a recursive process that may descend all the way down the widget hierarchy. The next step is to delegate the actual calculation of the minimum width and height needed for the contents of the widget (i.e. excluding padding) to do_claim(), which should be overridden in Widget subclasses. Finally, the claim is modified to account for padding and the corresponding private attributes are updated.

This method should not be called outside of a repack. If you’re using glooey to make a GUI, I can’t think of a scenario where you should call or override this method.

_detach_child(child)

Detach a child from this widget.

This method checks to make sure the child is currently attached to this widget, undraws the child, resets several of the child’s attributes that might have been set by this widget, and removes the child from an internal list of children widgets.

This method is only meant to be called in subclasses of Widget, which is why it’s prefixed with an underscore.

_draw()

Create or update the vertex lists needed to render the widget.

A widget should call this method whenever its appearance may have changed (e.g. because an attribute was set or something) but its size hasn’t. If its size may have changed, call _repack() instead. The actual drawing itself is delegated to do_draw(), so subclasses should implement that method instead of overriding this one. In order for a widget to be drawn, four conditions need to be met:

  1. The widget must be connected to the root of the widget hierarchy. Widgets get their pyglet batch object from the root widget, so without this connection they cannot be drawn.

  2. The widget must have a size specified by its rect attribute. This attribute is set when the widget is attached to the hierarchy and its parent calls its _resize() method.

  3. The widget must be associated with a pyglet graphics group, which controls things like how the widget will be stacked or scrolled. A group is set when the widget is attached to the hierarchy and its parent calls its _regroup() method.

  4. The widget must not be hidden.

_draw_all()

Draw this widget and all of its children.

_event_stack = ()
_filter_pending_updates()

Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active. This method is meant to be overridden by subclasses that want to customize how held updates are applied.

The self._pending_updates member variable is a list containing a (method, args, kwargs) tuple for each update that was called while updates were being held. This list is in the order that the updates were actually called, and any updates that were called more than once will appear in this list more than once.

This method should yield or return a list of the tuples in the same format representing the updates that should be applied, in the order they should be applied. The default implementation filters out duplicate updates without changing their order. In cases where it matters, the last call to each update is used to determine the order.

_get_handlers(args, kwargs)

Implement handler matching on arguments for set_handlers and remove_handlers.

_grab_mouse()

Force all mouse events to be funneled to this widget.

The mouse events will still pass through all of this widget’s parents. This is necessary because some of those parents may transform the mouse coordinates, e.g. for scrolling. However, the usual search for the children under the mouse is short-circuited and the events are always directed towards this widget.

This method will fail with an exception if another widget is already grabbing the mouse.

_hide_children()

Hide all of the widget’s children.

This method is part of the process of hiding the widget itself, so it is assumed that the widget is hidden when this method is called.

_init_group(group)

Set the pyglet.graphics.Group associated with this object, without invoking any of the callbacks that _regroup() would.

This method is only meant to be used in constructors—specifically Root.__init__()—where drawing/regrouping children doesn’t make sense and can create complications (e.g. the need for do_draw() to guard against uninitialized member variables).

static _raise_dispatch_exception(event_type, args, handler, exception)
_realign()

Update the amount of space available for the widget’s content, given the amount of space assigned to it by its parent.

Starting from the amount of space assigned to this widget by its parent, this means subtracting the padding, performing the proper alignment, and rounding to the nearest integer pixel to prevent seams from appearing. The final result is stored in self.__rect.

Three callbacks are invoked to allow the widget to react to this change: do_resize(), do_draw(), and do_resize_children(). The last initiates a recursive descent down the widget hierarchy updating the sizes of the widget’s children and all of their children, which is a critical part of the repacking process.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_regroup(new_group)

Change the pyglet.graphics.Group associated with this widget.

Four callbacks are invoked to allow the widget to react to this change. In the following order:

The last initiates a recursive descent down the widget hierarchy updating the groups of the widget’s children and all of their children.

_remove_handler(name, handler)

Used internally to remove all handler instances for the given event name.

This is normally called from a dead WeakMethod to remove itself from the event stack.

_repack()

Indicate that the widget’s size may have changed, and that the sizes of its children and parents may also need to change in response.

This method triggers a recursive update that first goes down the widget hierarchy figuring out how much space each widget needs, and then goes up the hierarchy figuring out how much space each widget gets.

The most common way to use this method is in setter functions in Widget subclasses, where the attribute being set might change the shape of the widget. If the attribute being set might change the widget’s appearance, but not it’s size, call _draw() instead.

_repack_and_regroup_children()

Resize and regroup the children of this widget if this widget is already attached to the GUI. Otherwise, don’t do anything.

Container widgets should call this method whenever a new child widget is attached.

Before a widget is attached to the GUI, it can’t have a size or a group because these attributes derive from a parent widget. If any children are attached to the widget at this point, they cannot be given sizes or groups for the same reason. Once the widget is attached to the GUI, it will be given a size and a group by its parent, then it will give sizes and groups to the children already attached to it. If any children are attached after this point, they should be given a size and group right away.

Note that what happens when a child widget is attached to its parent depends on whether the parent is already attached to the GUI or not. If it is, the child is resized and regrouped (other children may be resized and regrouped at the same time). Otherwise, nothing happens. This method handles this logic. As long as container subclasses call this method each time a child is added or removed, their children will be properly sized and grouped no matter when they were attached.

_replace_button(old_button, new_button, on_click)
_resize(new_rect)

Change the size or shape of this widget.

This method is triggered by _repack(), which recursively climbs the widget hierarchy to make space for the widgets that need it, then calls _resize() on any widget that need to adapt to the new space allocation.

This method should not be called outside of a repack, because it assumes that the claims have already been updated.

_undraw()

Delete the vertex lists being used to render this widget.

This method is called when the widget is hidden or removed from the GUI. The actual work is delegated to do_undraw(), so subclasses should implement that method rather than overriding this one.

_undraw_all()

Undraw this widget and all of its children.

_ungrab_mouse(x=None, y=None)

Release the mouse and allow mouse events to be handled as usual again.

If x and y coordinates are provided, an on_mouse_motion event will be triggered by the root widget. In some circumstances, this is necessary to get widgets to re-evaluate their appearance (e.g. rollover state) after the mouse is released.

It is not an error to call this method if the widget is not actually grabbing the mouse, it just won’t do anything.

_unhide_children(draw=True)

Redraw any of the widget’s children that were visible before the widget itself was hidden.

This method is part of the process of unhiding the widget, so it is assumed that the widget itself is already visible. We can’t simply draw every child, because some of the children may have been explicitly hidden independently of this one.

add(widget)

Add a widget to the frame.

This method just calls add() on whatever widget the Box class is. Normally Box is a Bin, so this makes sense. If you replace Box with something else, for example glooey.containers.Grid, you might want to also reimplement this method.

property alignment

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

property batch

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

property bottom_padding

Return the padding on the bottom of this widget.

property box

Return the widget holding the content of the frame.

property buttons
property claimed_height

Return the width needed to render this widget.

property claimed_rect

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

property claimed_size

Return the width and height needed to render this widget.

property claimed_width

Return the width needed to render this widget.

clear()

Remove any widgets from the frame.

close()
property content

Return the widget being displayed in the frame.

custom_alignment = 'center'

How the widget should align itself within the space assigned to it.

custom_autoadd_content = False

If a Content inner class is specified, automatically instantiate it and add it to the frame. This behavior in enabled by default.

custom_bottom_padding = None

How much space the widget should keep free on its bottom side.

This setting has priority over custom_vert_padding and custom_padding.

custom_box_layer = 2

The z-order for the contents of the frame (i.e. the box and its children). By default this is on top of the decorations.

custom_decoration_layer = 1

The z-order for the frame’s decorations (i.e. the border and the background). By default these are below the content.

custom_grab_mouse_on_click = False

Indicate that the widget should automatically grab the mouse when being clicked. This behavior is useful for widgets that emit interesting on_hold events, or that can be dragged around.

custom_height_hint = None

The user-set minimum height for this widget.

This setting has priority over custom_size_hint.

custom_horz_padding = None

How much space the widget should keep free around its left and right edges.

This setting has priority over custom_padding.

custom_left_padding = None

How much space the widget should keep free on its left side.

This setting has priority over custom_horz_padding and custom_padding.

custom_padding = None

How much space the widget should keep free around its edges.

custom_propagate_mouse_events = True

Whether or not this widget should propagate mouse events to its children.

This is useful for implementing composite widgets that want to handle mouse events without any duplication of effort or interference from their children.

custom_right_padding = None

How much space the widget should keep free on its right side.

This setting has priority over custom_horz_padding and custom_padding.

custom_size_hint = (0, 0)

The user-set minimum size for this widget.

The widget also calculates its own minimum size, based on the content it needs to fit within it. The size hint can make the widget smaller than its “internal” minimum size, but it can make it bigger.

custom_top_padding = None

How much space the widget should keep free on its top side.

This setting has priority over custom_vert_padding and custom_padding.

custom_vert_padding = None

How much space the widget should keep free around its top and bottom edges.

This setting has priority over custom_padding.

custom_width_hint = None

The user-set minimum width for this widget.

This setting has priority over custom_size_hint.

debug_drawing_problems()

Suggest reasons why a widget is not displaying.

It can be hard to debug problems when nothing is showing up on the screen, so this method is meant to help look for common reasons why that might be the case. The suggestions will be printed to stdout. Make sure to call this method after attaching the widget to the GUI hierarchy, otherwise you’ll just get a message saying the widget hasn’t been attached to the GUI yet.

debug_placement_problems(claimed='red', assigned='yellow', content='blue')

Draw boxes showing the widgets assigned, claimed, and content rectangles.

The claimed rect will always appear in the bottom left corner, because the claim is only a size, not a position. Sometimes the assigned rectangle can obscure the content rectangle, so be aware that that could happen.

property decoration

Return the widget appearing in the background of the frame.

disable()

Prevent the widget from reacting to the mouse.

In particular, this means disabling rollover and click/double-click events.

discard_updates()
dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters
event_typestr

Name of the event.

argssequence

Arguments to pass to the event handler.

Return type

bool or None

Returns

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earlier, the return value is always None.

do_attach()

React to the widget being attached to the GUI.

Specifically, this method is called when the widget becomes connected, through any number of parent widgets, to the root of the widget hierarchy. When this happens, self.root will return a widget rather than None.

Note that this method will not necessarily be called when the widget is simply added to a parent widget. If the parent is already attached to the GUI itself, then this method will be called right then. Otherwise, this method will be called when that parent (or one of its parents) is attached to the GUI.

This method is mainly useful for widgets that need to take control away from the root widget for some reason. For example, Viewport widgets override how mouse events are interpreted and Dialog widgets grab all the key and mouse events for themselves.

do_claim()

Return the minimum width and height needed to render this widget.

Most widgets need to implement this method. The exception is widgets that have exactly one child. In that case, there’s a reasonable default: claim just enough space for that child. Most composite widgets are covered by this default, because they typically have a container widget as their only child and attach any other widgets they need to that container.

do_detach()

React to the widget being detached from the GUI.

do_draw()

Draw any shapes or images associated with this widget.

This method is called by _draw() after it checks to make sure the widget is attached to the root of the GUI hierarchy and that the rect, group, and batch attributes have all been set.

This method is called both to draw the widget for the first time and to update it subsequently. This usually means that you need to check to see if your graphics objects and resources need to be initialized yet.

do_find_children_near_mouse(x, y)

Yield all the children that could be under the given mouse coordinate.

The order in which the children are yielded has no significance. It’s ok to yield children that are hidden or are not actually under the given coordinate; _Widget__find_children_under_mouse() will check these things for every widget produced by this method. However, failing to yield a child that actually is under the mouse will result in that child not responding to the mouse.

The default implementation just yields all of the widgets children, but subclasses may be able to use knowledge of their geometry to quickly yield a smaller set of children to check. Grid is a good example of a widget that does this.

do_regroup()

React to a change in the widget’s pyglet graphics group.

In pyglet, groups are used to control layers and OpenGL state. This method is called whenever the widget’s group is changed, for example when the widget is attached to the GUI or moved from one part of the GUI to another.

Only widgets that actually draw things need to implement this method, because groups aren’t used for anything but drawing. Widgets that contain other widgets may need to implement do_regroup_children() to describe how those children should be regrouped.

It’s not always trivial to change the group used to draw something in pyglet. The way to do this depends on what’s being drawn and whether or not it’s been drawn before. The simplest case are high-level APIs like pyglet.sprite.Sprite that allow you to simply change a group attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call the pyglet.graphics.Batch.migrate() method. This method needs to know the OpenGL mode (e.g. GL_QUADS) associated with the vertex list, so you will have to keep track of that.

Keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right group.

do_regroup_children()

React to changes that might require this widget’s children to be regrouped.

This method is called when the widget’s own group is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _regroup() on each one. The default implementation puts all the children in the same group as the widget itself.

do_resize()

React to a change in the widget’s size.

Only widgets that actually draw things need to implement this method. If the widget has children widgets that it may need to redistribute space between, it should do that in do_resize_children().

However, keep in mind that this method is called before the widget is drawn and may be called after it’s been undrawn, so any vertex lists created in the draw function may or may not exist yet/anymore. If those vertex lists don’t exist yet, there’s nothing this function needs to do. The _draw() function will be called when the widget’s ready to draw, and at that point the vertex lists should be created with the right size and shape.

do_resize_children()

React to changes that might require this widget’s children to be resized.

This method is called when the widget’s own size is changed or when children are attached to or detached from the widget. A typical implementation would iterate through all the children attached to the widget and call _resize() on each one.

do_undraw()

Delete any shapes or images associated with this widget. This method may be called before _draw().

enable()

Indicate that the widget should react to the mouse.

In particular, this means enabling rollover and click/double-click events. Most widgets are enabled by default.

event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
event_types = ['on_attach', 'on_detach', 'on_attach_child', 'on_detach_child', 'on_repack', 'on_regroup', 'on_mouse_press', 'on_mouse_release', 'on_mouse_hold', 'on_mouse_motion', 'on_mouse_enter', 'on_mouse_leave', 'on_mouse_drag', 'on_mouse_drag_enter', 'on_mouse_drag_leave', 'on_mouse_scroll', 'on_click', 'on_double_click', 'on_rollover', 'on_enable', 'on_disable', 'on_mouse_pan', 'on_edit_text', 'on_unfocus', 'on_focus', 'on_toggle', 'on_close', 'on_translate', 'on_resize_children', 'on_scroll']
get_alignment()

Return how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

get_batch()

Return the pyglet.graphics.Batch object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to interact with the batch when implementing do_draw().

get_bottom_padding()

Return the padding on the bottom of this widget.

get_box()

Return the widget holding the content of the frame.

get_buttons()
get_claimed_height()

Return the width needed to render this widget.

get_claimed_rect()

Return a vecrec.Rect indicating the amount of space needed to render this widget.

Only the width and height of the rectangle matter, the position is unimportant (and will in fact always be such that the lower left corner is at the origin).

get_claimed_size()

Return the width and height needed to render this widget.

get_claimed_width()

Return the width needed to render this widget.

get_content()

Return the widget being displayed in the frame.

get_decoration()

Return the widget appearing in the background of the frame.

get_grab_mouse_on_click()
get_group()

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

get_height()

Return the height of the widget.

get_height_hint()

Return the user-set minimum height for this widget.

get_horz_padding()

Return the padding on the left and right sides of this widget.

get_last_rollover_state()

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

get_left_padding()

Return the padding on the left side of this widget.

get_no_button()[source]
get_padded_rect()

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

get_padding()

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

get_parent()

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

get_propagate_mouse_events()

Return whether or not this widget will propagate mouse events to its children.

get_rect()

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

get_response()[source]
get_right_padding()

Return the padding on the right side of this widget.

get_rollover_state()

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

get_root()

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

get_size_hint()

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

get_top_padding()

Return the padding on the top of this widget.

get_total_horz_padding()

Return the sum of the padding on the left and right sides of this widget.

get_total_padding()

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

get_total_vert_padding()

Return the sum of the padding on the top and bottom of this widget.

get_vert_padding()

Return the padding on the top and bottom of this widget.

get_width()

Return the width of the widget.

get_width_hint()

Return the user-set minimum width for this widget.

get_window()

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

get_yes_button()[source]
property grab_mouse_on_click
property group

Return the pyglet.graphics.Group object being used to render the GUI, or None if this widget hasn’t been attached to the GUI yet.

You often need to use the group when implementing do_draw(), do_regroup(), and do_regroup_children().

property height

Return the height of the widget.

property height_hint

Return the user-set minimum height for this widget.

hide()

Make the widget invisible.

This will undraw the widget and prevent it from being redrawn until unhide() is called. During that time, the widget will not be visible, but it will still take up space in the GUI layout. If that’s not what you want, you should remove the widget from it container rather than simply hiding it. It’s safe to hide a widget that’s already hidden.

hold_updates()
property horz_padding

Return the padding on the left and right sides of this widget.

property is_attached_to_gui

True if the widget is part of the widget hierarchy.

property is_disabled

True if the widget can be clicked on.

This property is just the opposite of is_enabled.

property is_enabled

True if the widget can be clicked on.

See enable() for a precise description of what it means for a widget to be enabled.

property is_hidden

True if this widgets or one of its parents is hidden.

See hide() for a precise description of what it means for a widget to be hidden.

property is_root

True if this is the root of the widget hierarchy.

is_under_mouse(x, y)

Return true if the widget is under the given mouse coordinate.

The default implementation just checks the given coordinate against the widget’s rectangle, but you can reimplement this method in subclasses to support other geometries.

property is_visible

False if this widgets or one of its parents is hidden.

This property is just the opposite of is_hidden.

property last_rollover_state

Return a string specifying how the mouse was interacting with this widget before its most recent motion.

See get_rollover_state() for the list of possible rollover states.

property left_padding

Return the padding on the left side of this widget.

property no_button
on_click_no(widget)[source]
on_click_yes(widget)[source]
on_mouse_drag(x, y, dx, dy, buttons, modifiers)

React to the mouse being dragged within this widget.

The on_mouse_drag event is propagated to any children that remained under the mouse, an on_mouse_drag_enter event is triggered in any children that just came under the mouse, and an on_mouse_drag_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_drag_enter(x, y)

React to the mouse being dragged into this widget.

The on_mouse_drag_enter event is propagated to any children under the mouse.

on_mouse_drag_leave(x, y)

React to the mouse being dragged out of this widget.

The on_mouse_drag_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse), any on_mouse_hold event is stopped, and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_enter(x, y)

React to the mouse crossing into this widget.

The on_mouse_enter event is propagated to any children under the mouse and an on_rollover event is triggered to indicate that the widget’s rollover state is now “over”.

on_mouse_leave(x, y)

React to the mouse crossing out of this widget.

The on_mouse_leave event is propagated to any children that are no longer under the mouse (i.e. that aren’t grabbing the mouse) and an on_rollover event is triggered to indicate that the widget’s rollover state is now “base”.

on_mouse_motion(x, y, dx, dy)

React to the mouse moving within this widget.

The on_mouse_motion event is propagated to any children that remained under the mouse, an on_mouse_enter event is triggered in any children that just came under the mouse, and an on_mouse_leave event is triggered in any children that were previously under the mouse but no longer are.

on_mouse_press(x, y, button, modifiers)

React when the mouse is pressed on this widget.

The on_mouse_press` event is propagated to any children under the mouse, an ``on_mouse_hold event is started, and an on_rollover event is fired to indicate that the widget’s rollover state is now “down”.

on_mouse_release(x, y, button, modifiers)

React when the mouse is released over this widget.

The on_mouse_release` event is propagated to any children under the mouse, any ``on_mouse_hold event is stopped, an on_click event is fired if the click started and stopped without leaving the widget, and on_double_click event is triggered if the widget was clicked twice in the last 500 ms, and an on_rollover event is fired to indicate that the widget’s rollover state is now “over”.

on_mouse_scroll(x, y, scroll_x, scroll_y)

React to the mouse scroll wheel being turned.

The on_mouse_scroll event is propagated to any children under the mouse.

open(gui)[source]
property padded_rect

Return a vecrec.Rect indicating the amount of space needed for the widget’s content plus its padding.

This information is useful to container widgets, which need to work out how to arrange their children.

property padding

Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.

property parent

Return this widget’s parent, or None if this widget hasn’t been attached to the GUI yet.

pause_updates()
pop_handlers()

Pop the top level of event handlers off the stack.

property propagate_mouse_events

Return whether or not this widget will propagate mouse events to its children.

push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

property rect

Return the vecrec.Rect indicating where this widget is located on the screen.

This rectangle already accounts for the widget’s padding, alignment, and size hint, so when drawing you should just try to fill the whole rectangle.

classmethod register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters
namestr

Name of the event to register.

relay_events_from(originator, event_type, *more_event_types)

Configure this handler to re-dispatch events from another handler.

This method configures this handler dispatch an event of type event_type whenever originator dispatches events of the same type or any of the types in more_event_types. Any arguments passed to the original event are copied to the new event.

This method is mean to be useful for creating composite widgets that want to present a simple API by making it seem like the events being generated by their children are actually coming from them. See the Composing widgets tutorial for an example.

remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers(); and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters
namestr

Name of the event type to remove.

handlercallable

Event handler to remove.

remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers() for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers() and pop_handlers().

property response
resume_updates()
property right_padding

Return the padding on the right side of this widget.

property rollover_state

Return a string specifying how the mouse is currently interacting with this widget.

The interactions between each widget and the mouse are recalculated each time the mouse moves, i.e. on every on_mouse_motion event. The following rollover states exist:

“base”

The mouse is not interacting with the widget.

“over”

The mouse is on top of the widget.

“down”

The mouse is being pressed on the widget. If the mouse is released while in this state, an on_click event will be triggered.

property root

Return the top of the widget hierarchy, or None if this widget hasn’t been attached to the GUI yet.

set_alignment(new_alignment)

Set how this widget will be positioned within the space assigned to it.

The alignment can be either a string or a function. For more information, see the tutorial on Padding, alignment, and size hints or the API documentation for the glooey.drawing.alignment module.

set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_decoration(widget)

Set the widget appearing in the background of the frame.

set_grab_mouse_on_click(new_setting)
set_handler(name, handler)

Attach a single event handler.

Parameters
namestr

Name of the event type to attach to.

handlercallable

Event handler to attach.

set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers() for the accepted argument types.

set_height_hint(new_height)

Set the minimum height for this widget.

set_horz_padding(new_padding)

Set the padding for the left and right sides of this widget.

set_left_padding(new_padding)

Set the padding for the left side of this widget.

set_no_button(button)[source]
set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)

Set the padding for any or all sides of this widget.

set_propagate_mouse_events(new_setting)

Set whether or not this widget will propagate mouse events to its children.

set_right_padding(new_padding)

Set the padding for the right side of this widget.

set_size_hint(new_width, new_height)

Set the minimum size for this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

set_top_padding(new_padding)

Set the padding for the top of this widget.

set_vert_padding(new_padding)

Set the padding for the top and bottom of this widget.

set_width_hint(new_width)

Set the minimum width for this widget.

set_yes_button(button)[source]
property size_hint

Return the user-set minimum dimensions of this widget.

The widget cannot be smaller than either the claim (which is calculated internally by the widget based on its own geometry) of the size hint (which can be explicitly provided by the developer).

start_event(event_type, *args, dt=0.016666666666666666)

Begin dispatching the given event at the given frequency.

Calling this method will cause an event of type event_type with arguments args to be dispatched every dt seconds. This will continue until stop_event() is called for the same event.

These continuously firing events are useful if, for example, you want to make a button that scrolls for as long as it’s being held.

stop_event(event_type)

Stop dispatching the given event.

It is not an error to attempt to stop an event that was never started, the request will just be silently ignored.

suppress_updates()
property top_padding

Return the padding on the top of this widget.

property total_horz_padding

Return the sum of the padding on the left and right sides of this widget.

property total_padding

Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.

property total_vert_padding

Return the sum of the padding on the top and bottom of this widget.

unhide(draw=True)

Make the widget visible again.

This just undoes the effects of hide() and make the widget behave like normal again. It’s safe to unhide a widget that’s already unhidden.

property vert_padding

Return the padding on the top and bottom of this widget.

property width

Return the width of the widget.

property width_hint

Return the user-set minimum width for this widget.

property window

Return the pyglet.window.Window that the GUI is part of, or None if this widget hasn’t been attached to the GUI yet.

You can attach event handlers to the window to react to events that aren’t propagated through the widget hierarchy, e.g. key presses.

property yes_button