glooey.buttons.Button

class glooey.buttons.Button(*args, **kwargs)[source]

Bases: glooey.widget.Widget

A widget that is meant for the user to click on.

In order for the user to know that a widget is meant to be clicked on, the widget should react visually to the mouse. A common way to do this is to design different background images for the different rollover states, and to use those images behind a foreground (e.g. text) that doesn’t react to the mouse.

The role of the Button widget is to make it very easy to create button subclasses that follow this broad paradigm of having a fixed foreground and a mouse-responsive background. When subclassing Button, it should rarely be necessary to define more than a handful of custom attributes and maybe an inner class or two. Of course, if you want buttons that don’t follow the above paradigm (e.g. buttons that have mouse-responsive foregrounds, more than two layers, etc.), it may be simpler to create a custom widget derived from Widget than to shoehorn Button into a case it wasn’t meant for.

Buttons have four states with regard to the mouse. These are the same states managed by the Rollover widget:

  • base: The mouse is not interacting with the widget.

  • over: The mouse is hovering over the widget, but not pressed.

  • down: The mouse is actively clicking on the widget.

  • off: The widget has been deactivated and cannot be clicked on.

The widgets to use for the foreground and background of the button can be specified using inner classes, although the defaults are often sufficient. The foreground, which does not react to the mouse, is simply given by Button.Foreground. Any widget class can be used, but the two most common choices are glooey.text.Label (the default) and Image.

The background, which does react to the mouse, is composed of a different widget for each rollover state. Usually these widgets are all of the same class, which is given by the Button.Background inner class. However, it’s also possible to specify a different class for each state: Button.Base, Button.Over, Button.Down, Button.Off. Any background class must implement the following methods:

  • is_empty(): Return true if the widget has nothing to display

  • set_appearance(): Accept kwargs, change appearance accordingly.

glooey.images.Background (the default) and Image are the only two built-in widgets which implement these methods.

The most common way to customize a Button subclass is using custom attributes. You can specify different attributes for each background widget using the following shorthand notation: custom_<state>_<attr> = <value>. This ultimately results in set_appearance(<attr>=<value>) being called on the <state> background widget. Note that <attr> can be any valid python identifier. It can even include underscores. This allows custom widgets to be used seamlessly as background widgets, provided that they implement the required methods.

Custom Attributes:

Foreground([text, line_wrap])

The widget class to use for the foreground.

Background(**kwargs)

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

Base

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

Over

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

Down

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

Off

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

custom_alignment

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

custom_foreground_layer

The z-coordinate of the foreground widget.

custom_background_layer

The z-coordinate of the background widget.

custom_text

The text to display on the button.

custom_image

The image to display on the button.

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

foreground

background

base_background

over_background

down_background

off_background

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)

Create a new button widget.

click()

do_claim()

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

do_resize_children()

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

do_regroup_children()

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

get_foreground()

set_foreground(widget)

del_foreground()

set_background(**kwargs)

Set appearance options for any of the background widgets.

del_background()

get_base_background()

set_base_background(widget)

get_over_background()

set_over_background(widget)

get_down_background()

set_down_background(widget)

get_off_background()

set_off_background(widget)

Inherited from Widget

__init__(*args, **kwargs)

Create a new button 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)

Create a new button 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)

Create a new button 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:

_yield_layers()

_init_custom_background_appearances()

Setup the background widgets from parameters found in dynamically named custom_... class variables.

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.


class Background(**kwargs)[source]

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.

__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)[source]

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.

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

Off = None

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

Over = None

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

__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    A widget that is meant for the user to click on.\n\n    In order for the user to know that a widget is meant to be clicked on, the \n    widget should react visually to the mouse.  A common way to do this is to \n    design different background images for the different rollover states, and \n    to use those images behind a foreground (e.g. text) that doesn't react to \n    the mouse.\n\n    The role of the `Button` widget is to make it very easy to create button \n    subclasses that follow this broad paradigm of having a fixed foreground and \n    a mouse-responsive background.  When subclassing `Button`, it should \n    rarely be necessary to define more than a handful of custom attributes and \n    maybe an inner class or two.  Of course, if you want buttons that don't \n    follow the above paradigm (e.g. buttons that have mouse-responsive \n    foregrounds, more than two layers, etc.), it may be simpler to create a \n    custom widget derived from `Widget` than to shoehorn `Button` into a case \n    it wasn't meant for.\n\n    Buttons have four states with regard to the mouse.  These are the same \n    states managed by the `Rollover` widget:\n\n    - ``base``: The mouse is not interacting with the widget.\n    - ``over``: The mouse is hovering over the widget, but not \n      pressed.\n    - ``down``: The mouse is actively clicking on the widget.\n    - ``off``: The widget has been deactivated and cannot be clicked on.\n\n    The widgets to use for the foreground and background of the button can be \n    specified using inner classes, although the defaults are often sufficient.  \n    The foreground, which does not react to the mouse, is simply given by \n    `Button.Foreground`.  Any widget class can be used, but the two most common \n    choices are `Label` (the default) and `Image`.  \n\n    The background, which does react to the mouse, is composed of a different \n    widget for each rollover state.  Usually these widgets are all of the same \n    class, which is given by the `Button.Background` inner class.  However, \n    it's also possible to specify a different class for each state: \n    `Button.Base`, `Button.Over`, `Button.Down`, `Button.Off`.  Any background \n    class must implement the following methods:\n    \n    - is_empty(): Return true if the widget has nothing to display\n    - set_appearance(): Accept kwargs, change appearance accordingly.\n\n    `Background` (the default) and `Image` are the only two built-in widgets \n    which implement these methods.\n\n    The most common way to customize a `Button` subclass is using custom \n    attributes.  You can specify different attributes for each background \n    widget using the following shorthand notation: ``custom_<state>_<attr> = \n    <value>``.  This ultimately results in ``set_appearance(<attr>=<value>)`` \n    being called on the ``<state>`` background widget.  Note that ``<attr>`` \n    can be any valid python identifier.  It can even include underscores.  This \n    allows custom widgets to be used seamlessly as background widgets, provided \n    that they implement the required methods.\n    ", 'Foreground': <class 'glooey.buttons.Button.Foreground'>, 'Background': <class 'glooey.buttons.Button.Background'>, 'Base': None, 'Over': None, 'Down': None, 'Off': None, 'custom_alignment': 'center', 'custom_foreground_layer': 2, 'custom_background_layer': 1, 'custom_text': None, 'custom_image': None, '__init__': <function Button.__init__>, 'click': <function Button.click>, 'do_claim': <function Button.do_claim>, 'do_resize_children': <function Button.do_resize_children>, 'do_regroup_children': <function Button.do_regroup_children>, 'get_foreground': <function Button.get_foreground>, 'set_foreground': <function Button.set_foreground>, 'del_foreground': <function Button.del_foreground>, 'set_background': <function Button.set_background>, 'del_background': <function Button.del_background>, 'get_base_background': <function Button.get_base_background>, 'set_base_background': <function Button.set_base_background>, 'get_over_background': <function Button.get_over_background>, 'set_over_background': <function Button.set_over_background>, 'get_down_background': <function Button.get_down_background>, 'set_down_background': <function Button.set_down_background>, 'get_off_background': <function Button.get_off_background>, 'set_off_background': <function Button.set_off_background>, '_yield_layers': <function Button._yield_layers>, '_init_custom_background_appearances': <function Button._init_custom_background_appearances>, 'foreground': <property object>, 'background': <property object>, 'base_background': <property object>, 'over_background': <property object>, 'down_background': <property object>, 'off_background': <property object>, '__annotations__': {}})
__init__(*args, **kwargs)[source]

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.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_custom_background_appearances()[source]

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()[source]
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()[source]
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()[source]
del_foreground()[source]
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()[source]

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()[source]

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()[source]

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()[source]
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()[source]
get_foreground()[source]
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()[source]
get_over_background()[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_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)[source]

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)[source]
set_bottom_padding(new_padding)

Set the padding for the bottom of this widget.

set_down_background(widget)[source]
set_foreground(widget)[source]
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)[source]
set_over_background(widget)[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.

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.