glooey.text.Label¶
- class glooey.text.Label(text=None, line_wrap=None, **style)[source]¶
Bases:
glooey.widget.Widget
Custom Attributes:
Inherited from
Widget
How the widget should align itself within the space assigned to it.
How much space the widget should keep free around its edges.
How much space the widget should keep free around its left and right edges.
How much space the widget should keep free around its top and bottom edges.
How much space the widget should keep free on its left side.
How much space the widget should keep free on its right side.
How much space the widget should keep free on its top side.
How much space the widget should keep free on its bottom side.
The user-set minimum size for this widget.
The user-set minimum width for this widget.
The user-set minimum height for this widget.
Indicate that the widget should automatically grab the mouse when being clicked.
Whether or not this widget should propagate mouse events to its children.
Public Properties
Inherited from
Widget
True if this is the root of the widget hierarchy.
True if this widgets or one of its parents is hidden.
False if this widgets or one of its parents is hidden.
True if the widget can be clicked on.
True if the widget can be clicked on.
True if the widget is part of the widget hierarchy.
Return the user-set minimum dimensions of this widget.
Return the padding on all sides of this widget, as a (left, right, top bottom) tuple.
Return this widget's parent, or None if this widget hasn't been attached to the GUI yet.
Return the top of the widget hierarchy, or None if this widget hasn't been attached to the GUI yet.
Return the
pyglet.window.Window
that the GUI is part of, or None if this widget hasn't been attached to the GUI yet.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.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.Return the
vecrec.Rect
indicating where this widget is located on the screen.Return the width of the widget.
Return the height of the widget.
Return the user-set minimum width for this widget.
Return the user-set minimum height for this widget.
Return a
vecrec.Rect
indicating the amount of space needed to render this widget.Return the width and height needed to render this widget.
Return the width needed to render this widget.
Return the width needed to render this widget.
Return a
vecrec.Rect
indicating the amount of space needed for the widget's content plus its padding.Return the padding on the left and right sides of this widget.
Return the padding on the top and bottom of this widget.
Return the padding on the left side of this widget.
Return the padding on the right side of this widget.
Return the padding on the top of this widget.
Return the padding on the bottom of this widget.
Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.
Return the sum of the padding on the left and right sides of this widget.
Return the sum of the padding on the top and bottom of this widget.
Return how this widget will be positioned within the space assigned to it.
Return a string specifying how the mouse is currently interacting with this widget.
Return a string specifying how the mouse was interacting with this widget before its most recent motion.
Return whether or not this widget will propagate mouse events to its children.
Public Methods:
__init__
([text, line_wrap])Initialize the widget.
__repr__
()Return a succinct string identifying this widget.
do_claim
()Return the minimum width and height needed to render this widget.
do_draw
([ignore_rect])Draw any shapes or images associated with this widget.
Delete any shapes or images associated with this widget.
do_make_new_layout
(document, kwargs)on_insert_text
(start, text)on_delete_text
(start, end)get_text
()set_text
(text[, width])del_text
()set_font_name
(name)set_font_size
(size)get_bold
()set_bold
(bold)del_bold
()set_italic
(italic)set_underline
(underline)set_kerning
(kerning)set_baseline
(baseline)set_color
(color)set_background_color
(color)set_text_alignment
(alignment)set_line_spacing
(spacing)enable_line_wrap
(width)get_style
(style)set_style
(**style)del_style
(style)Inherited from
Widget
__init__
([text, line_wrap])Initialize the widget.
__repr__
()Return a succinct string identifying this widget.
__bool__
()Always consider widgets to be "true".
__len__
()Return the number of children this widget has.
__contains__
(widget)Return true if the given widget is one of this widget's children.
hide
()Make the widget invisible.
unhide
([draw])Make the widget visible again.
enable
()Indicate that the widget should react to the mouse.
disable
()Prevent the widget from reacting to the mouse.
React to the widget being attached to the GUI.
React to the widget being detached from the GUI.
do_claim
()Return the minimum width and height needed to render this widget.
React to a change in the widget's size.
React to changes that might require this widget's children to be resized.
React to a change in the widget's pyglet graphics group.
React to changes that might require this widget's children to be regrouped.
do_draw
([ignore_rect])Draw any shapes or images associated with this widget.
Delete any shapes or images associated with this widget.
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.
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.
Return the
pyglet.window.Window
that the GUI is part of, or None if this widget hasn't been attached to the GUI yet.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.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.Return the width of the widget.
Return the height of the widget.
Return the user-set minimum dimensions of this widget.
set_size_hint
(new_width, new_height)Set the minimum size for this widget.
Return the user-set minimum width for this widget.
set_width_hint
(new_width)Set the minimum width for this widget.
Return the user-set minimum height for this widget.
set_height_hint
(new_height)Set the minimum height for this widget.
Return a
vecrec.Rect
indicating the amount of space needed to render this widget.Return the width and height needed to render this widget.
Return the width needed to render this widget.
Return the width needed to render this widget.
Return a
vecrec.Rect
indicating the amount of space needed for the widget's content plus its 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.
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.
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.
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.
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.
Return the padding on the top of this widget.
set_top_padding
(new_padding)Set the padding for the top of this widget.
Return the padding on the bottom of this widget.
set_bottom_padding
(new_padding)Set the padding for the bottom of this widget.
Return the combined padding for both dimensions of this widget, as a (horizontal, vertical) tuple.
Return the sum of the padding on the left and right sides of this widget.
Return the sum of the padding on the top and bottom of this widget.
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.
Return a string specifying how the mouse is currently interacting with this widget.
Return a string specifying how the mouse was interacting with this widget before its most recent motion.
set_grab_mouse_on_click
(new_setting)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.
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__
([text, line_wrap])Initialize the widget.
relay_events_from
(originator, event_type, ...)Configure this handler to re-dispatch events from another handler.
start_event
(event_type, *args[, dt])Begin dispatching the given event at the given frequency.
stop_event
(event_type)Stop dispatching the given event.
Inherited from
EventDispatcher
register_event_type
(name)Register an event type with the dispatcher.
push_handlers
(*args, **kwargs)Push a level onto the top of the handler stack, then attach zero or more event handlers.
set_handlers
(*args, **kwargs)Attach one or more event handlers to the top level of the handler stack.
set_handler
(name, handler)Attach a single event handler.
Pop 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__
([text, line_wrap])Initialize the widget.
Private Properties
Inherited from
Widget
_Widget__num_children
Return the number of children attached to this widget.
_Widget__padding
Inherited from
EventDispatcher
Private Methods:
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.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 this widget and all of its children.
_undraw
()Delete the vertex lists being used to render this widget.
Undraw this widget and all of its children.
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 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
Return all the updates that need to be applied, from a list of all the updates that were called while the hold was active.
- __annotations__ = {}¶
- __bool__()¶
Always consider widgets to be “true”.
This behavior is meant to facilitate comparisons against None. This method has to be explicitly implemented because otherwise python would fallback on __len__(), which confusingly depends on whether or not the widget has children.
- __contains__(widget)¶
Return true if the given widget is one of this widget’s children.
- __dict__ = mappingproxy({'__module__': 'glooey.text', 'custom_text': '', 'custom_font_name': None, 'custom_font_size': None, 'custom_bold': None, 'custom_italic': None, 'custom_underline': None, 'custom_kerning': None, 'custom_baseline': None, 'custom_color': 'green', 'custom_background_color': None, 'custom_text_alignment': None, 'custom_line_spacing': None, '__init__': <function Label.__init__>, '__repr__': <function Label.__repr__>, 'do_claim': <function Label.do_claim>, 'do_draw': <function Label.do_draw>, 'do_undraw': <function Label.do_undraw>, 'do_make_new_layout': <function Label.do_make_new_layout>, 'on_insert_text': <function Label.on_insert_text>, 'on_delete_text': <function Label.on_delete_text>, 'get_text': <function Label.get_text>, 'set_text': <function Label.set_text>, 'del_text': <function Label.del_text>, 'get_font_name': <function Label.get_font_name>, 'set_font_name': <function Label.set_font_name>, 'del_font_name': <function Label.del_font_name>, 'get_font_size': <function Label.get_font_size>, 'set_font_size': <function Label.set_font_size>, 'del_font_size': <function Label.del_font_size>, 'get_bold': <function Label.get_bold>, 'set_bold': <function Label.set_bold>, 'del_bold': <function Label.del_bold>, 'get_italic': <function Label.get_italic>, 'set_italic': <function Label.set_italic>, 'del_italic': <function Label.del_italic>, 'get_underline': <function Label.get_underline>, 'set_underline': <function Label.set_underline>, 'del_underline': <function Label.del_underline>, 'get_kerning': <function Label.get_kerning>, 'set_kerning': <function Label.set_kerning>, 'del_kerning': <function Label.del_kerning>, 'get_baseline': <function Label.get_baseline>, 'set_baseline': <function Label.set_baseline>, 'del_baseline': <function Label.del_baseline>, 'get_color': <function Label.get_color>, 'set_color': <function Label.set_color>, 'del_color': <function Label.del_color>, 'get_background_color': <function Label.get_background_color>, 'set_background_color': <function Label.set_background_color>, 'del_background_color': <function Label.del_background_color>, 'get_text_alignment': <function Label.get_text_alignment>, 'set_text_alignment': <function Label.set_text_alignment>, 'del_text_alignment': <function Label.del_text_alignment>, 'get_line_spacing': <function Label.get_line_spacing>, 'set_line_spacing': <function Label.set_line_spacing>, 'del_line_spacing': <function Label.del_line_spacing>, 'enable_line_wrap': <function Label.enable_line_wrap>, 'disable_line_wrap': <function Label.disable_line_wrap>, 'get_style': <function Label.get_style>, 'set_style': <function Label.set_style>, 'del_style': <function Label.del_style>, '_update_style': <function Label._update_style>, '__doc__': None, 'text': <property object>, 'font_name': <property object>, 'font_size': <property object>, 'bold': <property object>, 'italic': <property object>, 'underline': <property object>, 'kerning': <property object>, 'baseline': <property object>, 'color': <property object>, 'background_color': <property object>, 'text_alignment': <property object>, 'line_spacing': <property object>, '__annotations__': {}})¶
- __init__(text=None, line_wrap=None, **style)[source]¶
Initialize the widget.
Don’t forget to call this method from subclasses!
- __len__()¶
Return the number of children this widget has.
- __module__ = 'glooey.text'¶
- __repr__()[source]¶
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
andself.__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 inWidget
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 todo_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: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.
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.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.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 fordo_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()
, anddo_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:
do_undraw()
- Called indirectly bydo_regroup()
and not by this method, so thiscan be overridden.
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
andy
coordinates are provided, anon_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 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
andcustom_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
andcustom_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
andcustom_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
andcustom_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.
- 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 byEventDispatcher
implementors; applications should call thedispatch_events
method.Since pyglet 1.2, the method returns
EVENT_HANDLED
if an event handler returnedEVENT_HANDLED
orEVENT_UNHANDLED
if all events returnedEVENT_UNHANDLED
. If no matching event handlers are in the stack,False
is returned.- Parameters
event_type
strName of the event.
args
sequenceArguments to pass to the event handler.
- Return type
bool or None
- Returns
(Since pyglet 1.2)
EVENT_HANDLED
if an event handler returnedEVENT_HANDLED
;EVENT_UNHANDLED
if one or more event handlers were invoked but returned onlyEVENT_UNHANDLED
; otherwiseFalse
. In pyglet 1.1 and earlier, the return value is alwaysNone
.
- 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(ignore_rect=False)[source]¶
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 therect
,group
, andbatch
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 agroup
attribute. On the other hand, if you’re drawing vertex lists yourself, you need to call thepyglet.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()[source]¶
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']¶
- 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_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_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()
, anddo_regroup_children()
.
- get_height()¶
Return the height of the widget.
- get_height_hint()¶
Return the user-set minimum height for this widget.
- get_horz_padding()¶
Return the padding on the left and right sides of this widget.
- get_last_rollover_state()¶
Return a string specifying how the mouse was interacting with this widget before its most recent motion.
See
get_rollover_state()
for the list of possible rollover states.
- get_left_padding()¶
Return the padding on the left side of this widget.
- get_padded_rect()¶
Return a
vecrec.Rect
indicating the amount of space needed for the widget’s content plus its padding.This information is useful to container widgets, which need to work out how to arrange their children.
- get_padding()¶
Return the padding on all sides of this widget, 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()
, anddo_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.
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_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, anon_mouse_drag_enter
event is triggered in any children that just came under the mouse, and anon_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), anyon_mouse_hold
event is stopped, and anon_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 anon_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 anon_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, anon_mouse_enter
event is triggered in any children that just came under the mouse, and anon_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 anon_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, anon_click
event is fired if the click started and stopped without leaving the widget, andon_double_click
event is triggered if the widget was clicked twice in the last 500 ms, and anon_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
name
strName 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
orpush_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
name
strName of the event type to remove.
handler
callableEvent 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()
andpop_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_bottom_padding(new_padding)¶
Set the padding for the bottom of this widget.
- set_grab_mouse_on_click(new_setting)¶
- set_handler(name, handler)¶
Attach a single event handler.
- Parameters
name
strName of the event type to attach to.
handler
callableEvent handler to attach.
- set_handlers(*args, **kwargs)¶
Attach one or more event handlers to the top level of the handler stack.
See
push_handlers()
for the accepted argument types.
- set_height_hint(new_height)¶
Set the minimum height for this widget.
- set_horz_padding(new_padding)¶
Set the padding for the left and right sides of this widget.
- set_left_padding(new_padding)¶
Set the padding for the left side of this widget.
- set_padding(all=None, *, horz=None, vert=None, left=None, right=None, top=None, bottom=None)¶
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 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.