Table Of Contents

Previous topic

Basic Structure of GUI

Next topic

Focus

Events

GUI has an own, very small event system that allows you to bind functions to some widget specific events. To do that, use the listen() method that takes an event name and a callback function that should accept any keyword arguments (**kwargs ). If a event occurs, all bound functions are called with the event specific arguments and two extra arguments, widget, a reference to the widget that raised the event, and event_name, the name of the event, in case you use one callback for multiple event types.

Widgets can listen to their own events as well. Do do that, just define a method with the name of the event prefixed by handle_. See the example below.

Widget implements the following standard events with these arguments:

  • resized (changed_w, changed_h)

    the widget was resized about the given values.

  • moved (changed_x, changed_y)

    the widget was moved about the given values.

  • hidden

    the widget was hidden

  • shown

    the widget was shown

  • focused

    the widget was focused

  • focus_lost

    the widget lost the focus

  • mouse_entered (pos)

    the mouse entered the widget at pos

  • mouse_left (last_pos)

    the mouse left the widget. Last mouse position above the widget was last_pos

  • mouse_dragged (buttons, rel, abs)

    the mouse was moved with at least one button pressed. For this event, the current mouse position can be outside the widget, but it was above it when the button was pressed. This event is limited to one per frame and widget.

    buttons is a list of 3 booleans that indicate which buttons are pressed.

    rel is the offset of the mouse relative to the point above the widget where the mouse was pressed. Use this if you want to drag the widget and pass it to the move method.

    abs is the absolute amount the mouse position one frame before

  • mouse_stopped_dragging (pos)

    all mouse buttons were released after dragging. pos may be a mouse position outside of Widget.rect.

  • mouse_down, mouse_up, mouse_moved (...)

    these events are equivalent to the standard pygame events MOUSEBUTTONDOWN, MOUSEBUTTONUP and MOUSEMOTION and have the same attributes. But they will occur only if the mouse is above the widget. (See Widget.collide_point())

Examples

A class listening to its own events

A Widget class that prints a message on when the mouse enters it.

class ExampleWidget(Widget):
    def __init__(self, *args, **kwargs):
         Widget.__init__(self, *args, **kwargs)

    def handle_mouse_entered(self, pos):
        print "Mouse entered ExampleWidget at %s" % pos

Listening to events of a certain instance

The same as above but only for one instance (and without a new class):

def my_callback(pos, **kwargs):
    print "Mouse entered ExampleWidget at %s" % pos

# create the widget (with the specific parameters that are omitted here)
my_widget = Widget(...)
# bind the callback function to the widget event
my_widget.listen("mouse_entered", my_callback)