Source

pygame / pygame / event.py

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
#!/usr/bin/env python

'''Pygame module for interacting with events and queues.

Pygame handles all it's event messaging through an event queue. The routines
in this module help you manage that event queue. The input queue is heavily
dependent on the pygame display module. If the display has not been
initialized and a video mode not set, the event queue will not really work.
 
The queue is a regular queue of Event objects, there are a variety of ways
to access the events it contains. From simply checking for the existance of
events, to grabbing them directly off the stack.
 
All events have a type identifier. This event type is in between the values
of NOEVENT and NUMEVENTS. All user defined events can have the value of
USEREVENT or higher. It is recommended make sure your event id's follow this
system.
 
To get the state of various input devices, you can forego the event queue
and access the input devices directly with their appropriate modules; mouse,
key, and joystick. If you use this method, remember that pygame requires some
form of communication with the system window manager and other parts of the
platform. To keep pygame in synch with the system, you will need to call
pygame.event.pump() to keep everything current. You'll want to call this
function usually once per game loop.
 
The event queue offers some simple filtering. This can help performance
slightly by blocking certain event types from the queue, use the
pygame.event.set_allowed() and pygame.event.set_blocked() to work with
this filtering. All events default to allowed.
 
Joysticks will not send any events until the device has been initialized.

An Event object contains an event type and a readonly set of member data.
The Event object contains no method functions, just member data. Event
objects are retrieved from the pygame event queue. You can create your
own new events with the pygame.event.Event() function.

Your program must take steps to keep the event queue from overflowing. If the
program is not clearing or getting all events off the queue at regular
intervals, it can overflow.  When the queue overflows an exception is thrown.
 
All Event objects contain an event type identifier in the Event.type member.
You may also get full access to the Event's member data through the Event.dict
method. All other member lookups will be passed through to the Event's
dictionary values.
 
While debugging and experimenting, you can print the Event objects for a
quick display of its type and members. Events that come from the system
will have a guaranteed set of member items based on the type. Here is a
list of the Event members that are defined with each type.

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
'''

__docformat__ = 'restructuredtext'
__version__ = '$Id$'

from copy import copy
from ctypes import *

from SDL import *
import pygame.base
import pygame.locals
import pygame.display

def pump():
    '''Internally process pygame event handlers.

    For each frame of your game, you will need to make some sort of call to
    the event queue. This ensures your program can internally interact with
    the rest of the operating system. If you are not using other event
    functions in your game, you should call pygame.event.pump() to allow
    pygame to handle internal actions.

    This function is not necessary if your program is consistently processing
    events on the queue through the other pygame.event functions.
     
    There are important things that must be dealt with internally in the event
    queue. The main window may need to be repainted or respond to the system.
    If you fail to make a call to the event queue for too long, the system may
    decide your program has locked up.
    '''
    pygame.display._video_init_check()
    SDL_PumpEvents()

def get(typelist=None):
    '''Get events from the queue.
    pygame.event.get(): return Eventlist
    pygame.event.get(type): return Eventlist
    pygame.event.get(typelist): return Eventlist

    This will get all the messages and remove them from the queue. If a type
    or sequence of types is given only those messages will be removed from the
    queue.

    If you are only taking specific events from the queue, be aware that the
    queue could eventually fill up with the events you are not interested.

    :Parameters:
        `typelist` : int or sequence of int
            Event type or list of event types that can be returned.

    :rtype: list of `Event`
    '''
    pygame.display._video_init_check()
    
    if not typelist:
        mask = SDL_ALLEVENTS
    else:
        if hasattr(typelist, '__len__'):
            mask = reduce(lambda a,b: a | SDL_EVENTMASK(b), typelist)
        else:
            mask = int(typelist)

    SDL_PumpEvents()

    events = []
    new_events = SDL_PeepEvents(1, SDL_GETEVENT, mask)
    while new_events:
        events.append(Event(0, sdl_event=new_events[0]))
        new_events = SDL_PeepEvents(1, SDL_GETEVENT, mask)
    return events


def poll():
    '''Get a single event from the queue.

    Returns a single event from the queue. If the event queue is empty an event
    of type pygame.NOEVENT will be returned immediately. The returned event is
    removed from the queue.

    :rtype: Event
    '''
    pygame.display._video_init_check()

    event = SDL_PollEventAndReturn()
    if event:
        return Event(0, sdl_event=event, keep_userdata=True)
    else:
        return Event(pygame.locals.NOEVENT)

def wait():
    '''Wait for a single event from the queue.

    Returns a single event from the queue. If the queue is empty this function
    will wait until one is created. While the program is waiting it will sleep
    in an idle state. This is important for programs that want to share the
    system with other applications.

    :rtype: Event
    '''
    pygame.display._video_init_check()

    return Event(0, sdl_event=SDL_WaitEventAndReturn())

def peek(typelist=None):
    '''Test if event types are waiting on the queue.

    Returns true if there are any events of the given type waiting on the
    queue.  If a sequence of event types is passed, this will return True if
    any of those events are on the queue.

    :Parameters:
        `typelist` : int or sequence of int
            Event type or list of event types to look for.

    :rtype: bool
    '''
    pygame.display._video_init_check()

    if not typelist:
        mask = SDL_ALLEVENTS
    else:
        if hasattr(typelist, '__len__'):
            mask = reduce(lambda a,b: a | SDL_EVENTMASK(b), typelist)
        else:
            mask = SDL_EVENTMASK(int(typelist))
    
    SDL_PumpEvents()
    events = SDL_PeepEvents(1, SDL_PEEKEVENT, mask)

    if not typelist:
        if events:
            return Event(0, sdl_event=events[0])
        else:
            return Event(pygame.locals.NOEVENT) # XXX deviation from pygame
    return len(events) > 0

def clear(typelist=None):
    '''Remove all events from the queue.

    Remove all events or events of a specific type from the queue. This has the
    same effect as `get` except nothing is returned. This can be slightly more
    effecient when clearing a full event queue.

    :Parameters:
        `typelist` : int or sequence of int
            Event type or list of event types to remove.
    
    '''
    pygame.display._video_init_check()
    
    if not typelist:
        mask = SDL_ALLEVENTS
    else:
        if hasattr(typelist, '__len__'):
            mask = reduce(lambda a,b: a | SDL_EVENTMASK(b), typelist)
        else:
            mask = int(typelist)

    SDL_PumpEvents()
    
    events = []
    new_events = SDL_PeepEvents(1, SDL_GETEVENT, mask)
    while new_events:
        new_events = SDL_PeepEvents(1, SDL_GETEVENT, mask)

_event_names = {
    SDL_ACTIVEEVENT:    'ActiveEvent',
    SDL_KEYDOWN:        'KeyDown',
    SDL_KEYUP:          'KeyUp',
    SDL_MOUSEMOTION:    'MouseMotion',
    SDL_MOUSEBUTTONDOWN:'MouseButtonDown',
    SDL_MOUSEBUTTONUP:  'MouseButtonUp',
    SDL_JOYAXISMOTION:  'JoyAxisMotion',
    SDL_JOYBALLMOTION:  'JoyBallMotion',
    SDL_JOYHATMOTION:   'JoyHatMotion',
    SDL_JOYBUTTONUP:    'JoyButtonUp',
    SDL_JOYBUTTONDOWN:  'JoyButtonDown',
    SDL_QUIT:           'Quit',
    SDL_SYSWMEVENT:     'SysWMEvent',
    SDL_VIDEORESIZE:    'VideoResize',
    SDL_VIDEOEXPOSE:    'VideoExpose',
    SDL_NOEVENT:        'NoEvent'
}

def event_name(event_type):
    '''Get the string name from an event id.

    Pygame uses integer ids to represent the event types. If you want to
    report these types to the user they should be converted to strings. This
    will return a the simple name for an event type. The string is in the
    CamelCase style.

    :Parameters:
     - `event_type`: int
          
    :rtype: str
    '''
    if event_type >= SDL_USEREVENT and event_type < SDL_NUMEVENTS:
        return 'UserEvent'
    return _event_names.get(event_type, 'Unknown')

def set_blocked(typelist):
    '''Control which events are allowed on the queue.

    The given event types are not allowed to appear on the event queue. By
    default all events can be placed on the queue. It is safe to disable an
    event type multiple times.

    If None is passed as the argument, this has the opposite effect and none of
    the event types are allowed to be placed on the queue.

    :Parameters:
        `typelist` : int or sequence of int or None
            Event type or list of event types to disallow.

    '''
    pygame.display._video_init_check()

    if typelist == None:
        SDL_EventState(SDL_ALLEVENTS, SDL_IGNORE)
    elif hasattr(typelist, '__len__'):
        for val in typelist:
            SDL_EventState(val, SDL_IGNORE)
    else:
        SDL_EventState(typelist, SDL_IGNORE)

def set_allowed(typelist):
    '''Control which events are allowed on the queue.

    The given event types are allowed to appear on the event queue. By default
    all events can be placed on the queue. It is safe to enable an event type
    multiple times.

    If None is passed as the argument, this has the opposite effect and all of
    the event types are allowed to be placed on the queue.

    :Parameters:
        `typelist` : int or sequence of int or None
            Event type or list of event types to disallow.

    '''
    pygame.display._video_init_check()

    if typelist == None:
        SDL_EventState(SDL_ALLEVENTS, SDL_ENABLE)
    elif hasattr(typelist, '__len__'):
        for val in typelist:
            SDL_EventState(val, SDL_ENABLE)
    else:
        SDL_EventState(typelist, SDL_ENABLE)

def get_blocked(event_type):
    '''Test if a type of event is blocked from the queue.

    Returns true if the given event type is blocked from the queue.

    :Parameters:
     - `event_type`: int

    :rtype: int
    '''
    pygame.display._video_init_check()

    if typelist == None:
        return SDL_EventState(SDL_ALLEVENTS, SDL_QUERY) == SDL_ENABLE
    elif hasattr(typelist, '__len__'):  # XXX undocumented behaviour
        for val in typelist:
            if SDL_EventState(val, SDL_QUERY) == SDL_ENABLE:
                return True
        return False
    else:
        return SDL_EventState(typelist, SDL_QUERY) == SDL_ENABLE
    
def set_grab(grab):
    '''Control the sharing of input devices with other applications.

    When your program runs in a windowed environment, it will share the mouse
    and keyboard devices with other applications that have focus. If your 
    program sets the event grab to True, it will lock all input into your
    program. 

    It is best to not always grab the input, since it prevents the user from
    doing other things on their system.

    :Parameters:
     - `grab`: bool

    '''
    pygame.display._video_init_check()

    if grab:
        SDL_WM_GrabInput(SDL_GRAB_ON)
    else:
        SDL_WM_GrabInput(SDL_GRAB_OFF)
    
def get_grab():
    '''Test if the program is sharing input devices.

    Returns true when the input events are grabbed for this application. Use
    `set_grab` to control this state.

    :rtype: bool
    '''
    pygame.display._video_init_check()

    return SDL_WM_GrabInput(SDL_GRAB_QUERY) == SDL_GRAB_ON

_USEROBJECT_CHECK1 = 0xdeadbeef
_USEROBJECT_CHECK2 = 0xfeedf00d
_user_event_objects = {}
_user_event_nextid = 0
    
def post(event):
    '''Place a new event on the queue.

    This places a new event at the end of the event queue. These Events will
    later be retrieved from the other queue functions.

    This is usually used for placing pygame.USEREVENT events on the queue.
    Although any type of event can be placed, if using the sytem event types
    your program should be sure to create the standard attributes with
    appropriate values.

    :Parameters:
        `event` : Event
            Event to add to the queue.

    '''
    global _user_event_nextid

    pygame.display._video_init_check()

    sdl_event = SDL_Event(pygame.locals.USEREVENT)
    sdl_event.code = _USEROBJECT_CHECK1
    sdl_event.data1 = c_void_p(_USEROBJECT_CHECK2)
    sdl_event.data2 = c_void_p(_user_event_nextid)
    _user_event_objects[_user_event_nextid] = event
    _user_event_nextid += 1

    SDL_PushEvent(sdl_event)

class Event:
    def __init__(self, event_type, event_dict=None, sdl_event=None, 
                 keep_userdata=False, **attributes):
        '''Create a new event object.

        Creates a new event with the given type. The event is created with the
        given attributes and values. The attributes can come from a dictionary
        argument, or as string keys from a dictionary. 

        The given attributes will be readonly attributes on the new event
        object itself. These are the only attributes on the Event object,
        there are no methods attached to Event objects.

        :Parameters:
            `event_type` : int
                Event type to create
            `event_dict` : dict
                Dictionary of attributes to assign.
            `sdl_event` : `SDL_Event`
                Construct a Pygame event from the given SDL_Event; used
                internally.
            `keep_userdata` : bool
                Used internally.
            `attributes` : additional keyword arguments
                Additional attributes to assign to the event.

        '''
        if sdl_event:
            if sdl_event.type == pygame.locals.USEREVENT and \
               sdl_event.code == _USEROBJECT_CHECK1 and \
               sdl_event.data1.value == _USEROBJECT_CHECK2 and \
               sdl_event.data2.value in _user_event_objects:
                # An event that was posted; grab dict from local store.
                id = sdl_event.data2.value
                for key, value in _user_event_objects[id].items():
                    setattr(self, key, value)
                # Free memory unless just peeking
                if not keep_userdata:
                    del _user_event_objects[id]
            else:    
                # Standard SDL event
                self.type = sdl_event.type
                if self.type == SDL_QUIT:
                    pass
                elif self.type == SDL_ACTIVEEVENT:
                    self.gain = sdl_event.gain
                    self.state = sdl_event.state
                elif self.type == SDL_KEYDOWN:
                    self.unicode = sdl_event.keysym.unicode
                    self.key = sdl_event.keysym.sym
                    self.mod = sdl_event.keysym.mod
                elif self.type == SDL_KEYUP:
                    self.key = sdl_event.keysym.sym
                    self.mod = sdl_event.keysym.mod
                elif self.type == SDL_MOUSEMOTION:
                    self.pos = (sdl_event.x, sdl_event.y)
                    self.rel = (sdl_event.xrel, sdl_event.yrel)
                    self.buttons = (sdl_event.state & SDL_BUTTON(1) != 0,
                                    sdl_event.state & SDL_BUTTON(2) != 0,
                                    sdl_event.state & SDL_BUTTON(3) != 0)
                elif self.type in (SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP):
                    self.pos = (sdl_event.x, sdl_event.y)
                    self.button = sdl_event.button
                elif self.type == SDL_JOYAXISMOTION:
                    self.joy = sdl_event.which
                    self.axis = sdl_event.axis
                    self.value = sdl_event.value / 32767.0
                elif self.type == SDL_JOYBALLMOTION:
                    self.joy = sdl_event.which
                    self.ball = sdl_event.ball
                    self.rel = (sdl_event.xrel, sdl_event.yrel)
                elif self.type == SDL_JOYHATMOTION:
                    self.joy = sdl_event.which
                    self.hat = sdl_event.hat
                    hx = hy = 0
                    if sdl_event.value & SDL_HAT_UP:
                        hy = 1
                    if sdl_event.value & SDL_HAT_DOWN:
                        hy = -1
                    if sdl_event.value & SDL_HAT_RIGHT:
                        hx = 1
                    if sdl_event.value & SDL_HAT_LEFT:
                        hx = -1
                    self.value = (hx, hy)
                elif self.type in (SDL_JOYBUTTONUP, SDL_JOYBUTTONDOWN):
                    self.joy = sdl_event.which
                    self.button = sdl_event.button
                elif self.type == SDL_VIDEORESIZE:
                    self.size = (sdl_event.w, sdl_event.h)
                    self.w = sdl_event.w
                    self.h = sdl_event.h
                elif self.type == SDL_VIDEOEXPOSE:
                    pass
                elif self.type == SDL_SYSWMEVENT:
                    pass ### XXX: not implemented
                elif self.type >= SDL_USEREVENT and self.type < SDL_NUMEVENTS:
                    self.code = sdl_event.code
        else:
            # Create an event (not from event queue)
            self.type = event_type
            if event_dict:
                for key, value in event_dict.items():
                    setattr(self, key, value)
            for key, value in attributes.items():
                setattr(self, key, value)

    def __repr__(self):
        d = copy(self.__dict__)
        del d['type']
        return '<Event(%d-%s %r)>' % \
            (self.type, event_name(self.type), d)

    def __nonzero__(self):
        return self.type != SDL_NOEVENT

EventType = Event
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.