olpcgames.eventwrap
index
/home/mcfletch/olpc/code/games-misc/olpcgames-src/doc/pydoc/olpcgames/eventwrap.py

Provides substitute for Pygame's "event" module using gtkEvent
 
Provides methods which will be substituted into Pygame in order to 
provide the synthetic events that we will feed into the Pygame queue.
These methods are registered by the "install" method.
 
This event queue does not support getting events only of a certain type. 
You need to get all pending events at a time, or filter them yourself. You 
can, however, block and unblock events of certain types, so that may be 
useful to you. 
 
Set_grab doesn't do anything (you are not allowed to grab events). Sorry.
 
Extensions:
 
    wait( timeout=None ) -- allows you to wait for only a specified period 
        before you return to the application.  Can be used to e.g. wait for a 
        short period, then release some resources, then wait a bit more, then
        release a few more resources, then a bit more...

 
Modules
       
Queue
gtk
logging
pygame
thread
threading
olpcgames.util

 
Classes
       
Queue
_FilterQueue
object
CallbackResult
Event

 
class CallbackResult(object)
     Methods defined here:
__call__(self)
Perform the actual callback in the Pygame event loop
__init__(self, callable, args, named, callContext=None)
Perform callback in Pygame loop with args and named
 
callContext is used to provide more information when there is 
a failure in the callback (for debugging purposes)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Event(object)
    Mock pygame events
 
  Methods defined here:
__init__(self, type, dict=None, **named)
Initialise the new event variables from dictionary and named become attributes
__repr__(self)
block(self)
Block until this event is finished processing
 
Event process is only finalized on the *next* call to retrieve an event
after the processing operation in which the event is processed.  In some 
extremely rare cases we might actually see that happen, were the 
file-saving event (for example) causes the Pygame event loop to exit.
In that case, the GTK event loop *could* hang.
retire(self)
Block the GTK event loop until this event is processed

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
dict

 
class _FilterQueue(Queue)
    Simple Queue sub-class with a put_left method
 
  Methods defined here:
get_type(self, filterFunction, block=True, timeout=None)
Get events of a given type
 
Note: can raise Empty *even* when blocking if someone else 
pops the event off the queue before we get around to it.
peek_type(self, filterFunction=<function <lambda> at 0x8f42b1c>)
Peek to see if we have filterFunction-matching element
 
Note: obviously this is *not* thread safe, it's just informative...

Methods inherited from Queue:
__init__(self, maxsize=0)
empty(self)
Return True if the queue is empty, False otherwise (not reliable!).
full(self)
Return True if the queue is full, False otherwise (not reliable!).
get(self, block=True, timeout=None)
Remove and return an item from the queue.
 
If optional args 'block' is true and 'timeout' is None (the default),
block if necessary until an item is available. If 'timeout' is
a positive number, it blocks at most 'timeout' seconds and raises
the Empty exception if no item was available within that time.
Otherwise ('block' is false), return an item if one is immediately
available, else raise the Empty exception ('timeout' is ignored
in that case).
get_nowait(self)
Remove and return an item from the queue without blocking.
 
Only get an item if one is immediately available. Otherwise
raise the Empty exception.
join(self)
Blocks until all items in the Queue have been gotten and processed.
 
The count of unfinished tasks goes up whenever an item is added to the
queue. The count goes down whenever a consumer thread calls task_done()
to indicate the item was retrieved and all work on it is complete.
 
When the count of unfinished tasks drops to zero, join() unblocks.
put(self, item, block=True, timeout=None)
Put an item into the queue.
 
If optional args 'block' is true and 'timeout' is None (the default),
block if necessary until a free slot is available. If 'timeout' is
a positive number, it blocks at most 'timeout' seconds and raises
the Full exception if no free slot was available within that time.
Otherwise ('block' is false), put an item on the queue if a free slot
is immediately available, else raise the Full exception ('timeout'
is ignored in that case).
put_nowait(self, item)
Put an item into the queue without blocking.
 
Only enqueue the item if a free slot is immediately available.
Otherwise raise the Full exception.
qsize(self)
Return the approximate size of the queue (not reliable!).
task_done(self)
Indicate that a formerly enqueued task is complete.
 
Used by Queue consumer threads.  For each get() used to fetch a task,
a subsequent call to task_done() tells the queue that the processing
on the task is complete.
 
If a join() is currently blocking, it will resume when all items
have been processed (meaning that a task_done() call was received
for every item that had been put() into the queue).
 
Raises a ValueError if called more times than there were items
placed in the queue.

 
Functions
       
_processCallbacks(events)
Process any callbacks in events and remove from the stream
_recordEvents(events)
Record the set of events to retire on the next iteration
_releaseEvents()
Release/retire previously-processed events
_typeChecker(types)
Create check whether an event is in types
clear()
Clears the entire pending queue of events 
 
Rarely used
event_name(...)
pygame.event.event_name(event type) -> string
name for event type
 
Returns the standard SDL name for an event type. Mainly helpful
for debugging, when trying to determine what the type of an event
is.
get(types=None)
Get a list of all pending events
 
types -- either an integer event-type or a sequence of integer event types 
    which restrict the set of event-types returned from the queue.  Keep in mind 
    that if you do not remove events you may wind up with an eternally growing
    queue or a full queue.  Normally you will want to remove all events in your 
    top-level event-loop and propagate them yourself.
 
    Note: if you use types you lose all event ordering guarantees, events
    may show up after events which were originally produced before them due to 
    the re-ordering of the queue on filtering!
get_blocked(*args, **kwargs)
get_grab()
This method will not be implemented
install()
Installs this module (eventwrap) as an in-place replacement for the pygame.event module.
 
Use install() when you need to interact with Pygame code written
without reference to the olpcgames wrapper mechanisms to have the 
code use this module's event queue.
 
XXX Really, use it everywhere you want to use olpcgames, as olpcgames
registers the handler itself, so you will always wind up with it registered when 
you use olpcgames (the gtkEvent.Translator.hook_pygame method calls it).
makeseq(obj)
Accept either a scalar object or a sequence, and return a sequence
over which we can iterate. If we were passed a sequence, return it
unchanged. If we were passed a scalar, return a tuple containing only
that scalar. This allows the caller to easily support one-or-many.
peek(types=None)
True if there is any pending event
 
types -- optional set of event-types used to check whether 
    an event is of interest.  If specified must be either a sequence 
    of integers/longs or an integer/long.
poll()
Get the next pending event if exists. Otherwise, return pygame.NOEVENT.
post(event)
Post a new event to the Queue of events
pump()
Handle any window manager and other external events that aren't passed to the user
 
Call this periodically (once a frame) if you don't call get(), poll() or wait()
pygame_get = get(...)
pygame.event.get([type]) -> list of Events
get all of an event type from the queue
 
Pass this a type of event that you are interested in, and it will
return a list of all matching event types from the queue. If no
types are passed, this will return all the events from the queue.
You may also optionally pass a sequence of event types. For
example, to fetch all the keyboard events from the queue, you
would call, 'pygame.event.get([KEYDOWN,KEYUP])'.
pygame_pump = pump(...)
pygame.event.pump() -> None
update the internal messages
 
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 pump() to allow
pygame to handle internal actions.
 
There are important things that must be dealt with internally in the
event queue. The main window may need to be repainted. Certain joysticks
must be polled for their values. If you fail to make a call to the event
queue for too long, the system may decide your program has locked up.
set_allowed(item)
Allow item/items to be added to the event queue
set_blocked(item)
Block item/items from being added to the event queue
set_grab(grabbing)
This method will not be implemented
wait(timeout=None)
Get the next pending event, wait up to timeout if none
 
timeout -- if present, only wait up to timeout seconds, if we 
    do not find an event before then, return None.  timeout 
    is an OLPCGames-specific extension.

 
Data
        _EVENTS_TO_RETIRE = []
g_blockAll = False
g_blocked = set([])
g_blockedlock = <thread.lock object at 0x87c24b0>
g_events = <olpcgames.eventwrap._FilterQueue instance at 0x8f46e0c>