pygame Event handling Event loop

Example

Pygame will register all events from the user into an event queue which can be received with the code pygame.event.get(). Every element in this queue is an Event object and they'll all have the attribute type, which is an integer representing what kind of event it is. In the pygame module there are predefined integer constants representing the type. Except for this attribute, events have different attributes.

Constant name	Attributes
QUIT	none
ACTIVEEVENT	gain, state
KEYDOWN	unicode, key, mod
KEYUP	key, mod
MOUSEMOTION	pos, rel, buttons
MOUSEBUTTONUP	pos, button
MOUSEBUTTONDOWN	pos, button
JOYAXISMOTION	joy, axis, value
JOYBALLMOTION	joy, ball, rel
JOYHATMOTION	joy, hat, value
JOYBUTTONUP	joy, button
JOYBUTTONDOWN	joy, button
VIDEORESIZE	size, w, h
VIDEOEXPOSE	none
USEREVENT	code

Example

To handle our events we simply loop through the queue, check what type it is (with the help of the predefined constants in the pygame module) and then perform some action. This code will check if the user has pressed the close button on the top corner of the display, and if so terminate the program.

for event in pygame.event.get():
    if event.type == pygame.QUIT:
        # Close the program any way you want, or troll users who want to close your program.
        raise SystemExit

ATTENTION: You have to call the event queue regularly when using pygame! Apart from fetching the available events, calling the event queue is also the way of pygame to interact with the operating system internally. If the event queue isn't called regularly, your operating system will assume that your program doesn't work correctly anymore and possibly make it look like the program crashed (in Windows the window becomes white). If you don't want to do anything with the events you should call pygame.event.pump() every game loop to make pygame process the events internally.

---

Keyboard events

There are two types of key events in pygame: KEYDOWN and KEYUP. These events have an attribute key which is an integer representing a key on the keyboard. The pygame module has predefined integer constants representing all the common keys. The constants are named with a capital K, an underscore and the name of the key. For example, <- is named K_BACKSPACE, a is named K_a and F4 is namned K_F4.

Example

This code will check if the user has pressed w, a, s or d.

for event in pygame.event.get():
    if event.type == pygame.QUIT:  # Usually wise to be able to close your program.
        raise SystemExit
    elif event.type == pygame.KEYDOWN:
        if event.key == pygame.K_w:
            print("Player moved up!")
        elif event.key == pygame.K_a:
            print("Player moved left!")
        elif event.key == pygame.K_s:
            print("Player moved down!")
        elif event.key == pygame.K_d:
            print("Player moved right!")

Modifiers

There is no integer constant for capital letters. Instead, key events have another attribute called mod, which is the modifiers (shift, ctrl, alt etc.) being pressed simultaneously as the key. The mod attribute is an integer representing the modifier being pressed. Each modifier's integer value are stored in the pygame module under the name of KMOD_ and their name. For example, Left shift is named KMOD_LSHIFT, Tab is named KMOD_TAB and Ctrl is named KMOD_CTRL.

Example

This code will check wether the user pressed a, Left shift + a or Caps + a.

for event in pygame.event.get():
    if event.type == pygame.QUIT:  # It's still wise to be able to close your program.
        raise SystemExit
    elif event.type == pygame.KEYDOWN:
        if event.key == pygame.K_a:
            if event.mod == 0:  # No modifier.
                print("You pressed 'a'")
            elif event.mod == pygame.KMOD_LSHIFT or event.mod == pygame.KMOD_CAPS:
                print("You pressed 'A'")
            else:
                print("You pressed 'a' with another modifier than right shift or caps.")

---

Mouse events

There are three types of mouse events in pygame MOUSEMOTION, MOUSEBUTTONDOWN and MOUSEBUTTONUP. Pygame will register these events when a display mode has been set.

MOUSEMOTION is received when the user moves his or her mouse in the display. It has the attributes buttons, pos and rel.

• buttons is a tuple representing if the mouse buttons (left, mouse-wheel, right) are being pressed or not.
• pos is the absolute position (x, y) of the cursor in pixels.
• rel is the position relative to the previous position (rel_x, rel_y) in pixels.

MOUSEBUTTONDOWN and MOUSEBUTTONUP is received when the user presses or releases a mouse button. They have the attributes button and pos.

• button is an integer representing the button being pressed. 1 for left button, 2 for mouse-wheel and 3 for right button.
• pos is the absolute position of the mouse (x, y) when the user pressed the mouse button.

Example

Here's a short example using some of the attributes of each mouse event:

for event in pygame.event.get():
    if event.type == pygame.QUIT:  # Close your program if the user wants to quit.
        raise SystemExit
    elif event.type == pygame.MOUSEMOTION:
        if event.rel[0] > 0:  # 'rel' is a tuple (x, y). 'rel[0]' is the x-value.
            print("You're moving the mouse to the right")
        elif event.rel[1] > 0:  # pygame start y=0 at the top of the display, so higher y-values are further down.
            print("You're moving the mouse down")
    elif event.type == pygame.MOUSEBUTTONDOWN:
        if event.button == 1:
            print("You pressed the left mouse button")
        elif event.button == 3:
            print("You pressed the right mouse button")
    elif event.type == pygame.MOUSEBUTTONUP:
        print("You released the mouse button")

Since there are no predefined constants for the mouse button attribute in the pygame module, here's the values for each:

Button	Value
Left mouse button	1
Mouse wheel button	2
Right mouse button	3
Mouse wheel scroll up	4
Mouse wheel scroll down	5

Scrolling the mouse button will generate pygame.MOUSEBUTTONDOWN and pygame.MOUSEBUTTONUP events.